Спасибо за такой подробный разбор, это именно тот уровень обсуждения, ради которого стоит писать на Хабр.
Вы правы: пример в статье не показывает полное покрытие фичи, и мы этого не скрываем. Его урезали сознательно, чтобы показать сам путь «страница документации → тест-кейсы → код», а не превращать статью в листинг на несколько экранов. Статья всё-таки про подход, а не про конкретный набор тестов, и код здесь иллюстрация, а не образец. Но по вашему комментарию видно, что пример получился слишком микро: без позитивного сценария с письмом он скорее путает, чем иллюстрирует.
Спасибо, за подробное разьяснение. полностью согласен: тесту нужно и то и другое.
И зря вы думаете, что сверка с макетом нам не интересна. Документация описывает, как продукт должен работать, а не как он должен выглядеть, так что вёрстку по ней не проверишь. Ваш подход как раз закрывает эту часть.
Интересно, как ваша система поступает, когда источники расходятся: документация говорит одно, а на скриншоте другое. Кому она верит — или выносит это человеку как кандидата в баг? и бывает ли такое в принципе?
Конь у нас вполне реальный: автотесты гоняются по живому продукту, а не по документации. Документация задаёт, как продукт должен себя вести, а проверяется это на самом приложении.
Со скриншотами есть обратная проблема. Скриншот показывает, как продукт ведёт себя сейчас, включая баги. Если писать тесты только по нему, легко закрепить текущее поведение как правильное. Документация как раз отвечает на вопрос «а так задумано?».
Но в одном вы правы: скриншоты — ценный источник, и мы прямо пишем в статье, что пока не научились нормально их использовать. Так что подход «документация плюс скриншоты» нам интересен. Расскажите, как у вас это устроено с локальной моделью: что она делает со скриншотом — распознаёт элементы, сверяет с макетом?
Хорошо, когда люди находят способы упростить сложные процессы. Побольше бы таких практических кейсов.
В ту же копилку: У нас на платформе тоже есть интересный практический опыт применения скриптов для автоматизации жизненного цикла документации. Описали как с помощью API Документерры, nginx и bash‑скриптов собрать собственный статический генератор контента и публиковать его мгновенно: проектами заведует не человек, а автоматизация, и обновления становятся доступными пользователям буквально за секунды.
У нас интегрированный подход: обращаемся к внешнему ИИ, но он не имеет доступа ко всей базе данных. В обработку передаётся только набор наиболее релевантных публичных страниц, которые предварительно отбираются нашим поисковым механизмом (FTS) по конкретному запросу. Получается бот работает с заранее отфильтрованным контекстом, без прямого доступа к данным платформы целиком.
В продолжение темы ИИ-помощников для работы с документацией можно упомянуть ИИ ПомощникаДокументерры. Он работает в формате чат-бота, понимает естественный язык и отвечает строго на основе вашей документации, всегда давая прямые ссылки на первоисточник.
Из плюсов:
можно подключать к открытым и закрытым публикациям с учётом прав доступа;
гибко настраивается видимость (для всех, только для авторизованных или только для гостей);
настраивается стиль общения и поведение бота через подсказки;
есть API, поэтому помощника можно встроить в собственные приложения или порталы;
хорошо подходит как для внутренней поддержки сотрудников, так и для внешних порталов знаний.
Инструмент может быть полезен как для внутренней базы знаний, так и для внешней документации или справочных порталов.
Хороший обзор, много полезных деталей. Мы (команда Документерры) читаем такие разборы с интересом. Если будете дополнять подборку или делать продолжение, будем рады, если посмотрите и на наш продукт — интересно узнать ваше мнение со стороны.
В случае с Wi-Fi действительно существует несколько вариантов написания, но всё зависит от контекста. Если речь идет о торговой марке, то правильным будет именно Wi-Fi, как зарегистрированный товарный знак. В других случаях — когда это просто описание технологии или стандарта — можно использовать wifi (с маленькими буквами). Однако важно придерживаться единого стиля внутри документации, чтобы не запутать читателя. В некоторых компаниях принято всё-таки использовать Wi-Fi, даже в общем контексте, чтобы сохранить узнаваемость бренда. Главное — согласованность! 😉
ГОСТы, конечно, хороши для форматов и структуры, но когда речь идет о стиле, тут уже не обойтись без гибкости. ГОСТ Р 2.105—2019 и ГОСТ 19, конечно, задают основы для оформления документации, но стиль — это про тон, голос, восприятие и работу с пользователем. Для этого как раз и нужны внутренние руководства по стилю. В них прописывают все нюансы: от того, как обращаться к пользователю, до того, как правильно передавать идеи и чувства через текст. ГОСТы тут не помогут, да и не должны!
Абсолютно согласен! Прокрастинация сама по себе неприятна, но когда к ней добавляется самобичевание, получается замкнутый круг: откладываешь -> винишь себя -> ещё сложнее начать.
Спасибо за рекомендацию, «Война за креатив» — отличная книга, особенно для тех, кто работает в творческой сфере. Ещё могу посоветовать «Легкий способ перестать откладывать дела на потом» Нила Фьоре — там много практических техник, которые помогают выйти из этого состояния без лишнего стресса.
Отличный выбор! Книга Стивена Кинга "Как писать книги" действительно заслуживает внимания — он здорово рассказывает не только о ремесле, но и о самом процессе письма, дисциплине и вдохновении. И хотя она не совсем про техническое письмо, многие советы универсальны. Спасибо за рекомендацию!
Полностью согласен, что унификация терминологии влияет не только на удобочитаемость, но и на более глубокие аспекты коммуникации, такие как доверие и эффективность обучения. Поэтому системный подход к терминологии — это не просто вопрос удобства, а стратегическая задача, влияющая на качество документации, обучение и взаимодействие в профессиональной среде.
Этот пример как раз подтверждает, почему важно четко определять термины в документации. Если их использовать как взаимозаменяемые без уточнения контекста, это может привести к недопониманию или даже ошибкам в эксплуатации оборудования.
Поэтому при унификации терминологии важно не просто свести все варианты к одному термину, а четко зафиксировать различия и привести их в глоссарий. Возможно, лучше указывать не просто «один и тот же объект», а группу устройств с разными принципами работы, но схожим назначением. Спасибо за точное замечание!
Спасибо за такой подробный разбор, это именно тот уровень обсуждения, ради которого стоит писать на Хабр.
Вы правы: пример в статье не показывает полное покрытие фичи, и мы этого не скрываем. Его урезали сознательно, чтобы показать сам путь «страница документации → тест-кейсы → код», а не превращать статью в листинг на несколько экранов. Статья всё-таки про подход, а не про конкретный набор тестов, и код здесь иллюстрация, а не образец. Но по вашему комментарию видно, что пример получился слишком микро: без позитивного сценария с письмом он скорее путает, чем иллюстрирует.
Спасибо, за подробное разьяснение. полностью согласен: тесту нужно и то и другое.
И зря вы думаете, что сверка с макетом нам не интересна. Документация описывает, как продукт должен работать, а не как он должен выглядеть, так что вёрстку по ней не проверишь. Ваш подход как раз закрывает эту часть.
Интересно, как ваша система поступает, когда источники расходятся: документация говорит одно, а на скриншоте другое. Кому она верит — или выносит это человеку как кандидата в баг? и бывает ли такое в принципе?
Конь у нас вполне реальный: автотесты гоняются по живому продукту, а не по документации. Документация задаёт, как продукт должен себя вести, а проверяется это на самом приложении.
Со скриншотами есть обратная проблема. Скриншот показывает, как продукт ведёт себя сейчас, включая баги. Если писать тесты только по нему, легко закрепить текущее поведение как правильное. Документация как раз отвечает на вопрос «а так задумано?».
Но в одном вы правы: скриншоты — ценный источник, и мы прямо пишем в статье, что пока не научились нормально их использовать. Так что подход «документация плюс скриншоты» нам интересен. Расскажите, как у вас это устроено с локальной моделью: что она делает со скриншотом — распознаёт элементы, сверяет с макетом?
Удалить можно, но тогда некому будет находить баги, о которых модель по ходу пишет в отчётах. Придётся снова ловить их руками, а мы только отвыкли )
А если серьёзно: тест-кейсы у нас проверяет человек, так что пустышки отсеиваются ещё до кода.
Отличная статья, очень полезно, когда автор делится реальными практическими сценариями автоматизации!
На эту тему у нас тоже есть похожий кейс (не open-source конечно, но тоже интересно): https://documenterra.ru/static-site-generator-svoimi-rukami-gotovim-iz-api-dokumenterry-nginx-i-shhepotki-bash/
Хорошо, когда люди находят способы упростить сложные процессы. Побольше бы таких практических кейсов.
В ту же копилку: У нас на платформе тоже есть интересный практический опыт применения скриптов для автоматизации жизненного цикла документации. Описали как с помощью API Документерры, nginx и bash‑скриптов собрать собственный статический генератор контента и публиковать его мгновенно: проектами заведует не человек, а автоматизация, и обновления становятся доступными пользователям буквально за секунды.
Подробнее про этот кейс можно прочитать здесь: https://documenterra.ru/static-site-generator-svoimi-rukami-gotovim-iz-api-dokumenterry-nginx-i-shhepotki-bash/
У нас есть интересный кейс с университетом — как своими руками собрали SSG под конкретную задачу и убрали рутину из процесса обновления методичек.
У нас интегрированный подход: обращаемся к внешнему ИИ, но он не имеет доступа ко всей базе данных. В обработку передаётся только набор наиболее релевантных публичных страниц, которые предварительно отбираются нашим поисковым механизмом (FTS) по конкретному запросу. Получается бот работает с заранее отфильтрованным контекстом, без прямого доступа к данным платформы целиком.
В продолжение темы ИИ-помощников для работы с документацией можно упомянуть ИИ Помощника Документерры. Он работает в формате чат-бота, понимает естественный язык и отвечает строго на основе вашей документации, всегда давая прямые ссылки на первоисточник.
Из плюсов:
можно подключать к открытым и закрытым публикациям с учётом прав доступа;
гибко настраивается видимость (для всех, только для авторизованных или только для гостей);
настраивается стиль общения и поведение бота через подсказки;
есть API, поэтому помощника можно встроить в собственные приложения или порталы;
хорошо подходит как для внутренней поддержки сотрудников, так и для внешних порталов знаний.
Инструмент может быть полезен как для внутренней базы знаний, так и для внешней документации или справочных порталов.
Хороший обзор, много полезных деталей. Мы (команда Документерры) читаем такие разборы с интересом. Если будете дополнять подборку или делать продолжение, будем рады, если посмотрите и на наш продукт — интересно узнать ваше мнение со стороны.
Если расширять картину рынка, то ещё есть Документерра, тоже далеко не новичок для структурированной работы с документами.
Жаль, что так поздно попалась статья. А то бы предложил потестить Документерру
В случае с Wi-Fi действительно существует несколько вариантов написания, но всё зависит от контекста. Если речь идет о торговой марке, то правильным будет именно Wi-Fi, как зарегистрированный товарный знак. В других случаях — когда это просто описание технологии или стандарта — можно использовать wifi (с маленькими буквами). Однако важно придерживаться единого стиля внутри документации, чтобы не запутать читателя. В некоторых компаниях принято всё-таки использовать Wi-Fi, даже в общем контексте, чтобы сохранить узнаваемость бренда. Главное — согласованность! 😉
👍
ГОСТы, конечно, хороши для форматов и структуры, но когда речь идет о стиле, тут уже не обойтись без гибкости. ГОСТ Р 2.105—2019 и ГОСТ 19, конечно, задают основы для оформления документации, но стиль — это про тон, голос, восприятие и работу с пользователем. Для этого как раз и нужны внутренние руководства по стилю. В них прописывают все нюансы: от того, как обращаться к пользователю, до того, как правильно передавать идеи и чувства через текст. ГОСТы тут не помогут, да и не должны!
А какие именно приложения вам помогли? Может, есть фавориты, которые до сих пор используете?
Абсолютно согласен! Прокрастинация сама по себе неприятна, но когда к ней добавляется самобичевание, получается замкнутый круг: откладываешь -> винишь себя -> ещё сложнее начать.
Спасибо за рекомендацию, «Война за креатив» — отличная книга, особенно для тех, кто работает в творческой сфере. Ещё могу посоветовать «Легкий способ перестать откладывать дела на потом» Нила Фьоре — там много практических техник, которые помогают выйти из этого состояния без лишнего стресса.
Отличный выбор! Книга Стивена Кинга "Как писать книги" действительно заслуживает внимания — он здорово рассказывает не только о ремесле, но и о самом процессе письма, дисциплине и вдохновении. И хотя она не совсем про техническое письмо, многие советы универсальны. Спасибо за рекомендацию!
Полностью согласен, что унификация терминологии влияет не только на удобочитаемость, но и на более глубокие аспекты коммуникации, такие как доверие и эффективность обучения. Поэтому системный подход к терминологии — это не просто вопрос удобства, а стратегическая задача, влияющая на качество документации, обучение и взаимодействие в профессиональной среде.
Этот пример как раз подтверждает, почему важно четко определять термины в документации. Если их использовать как взаимозаменяемые без уточнения контекста, это может привести к недопониманию или даже ошибкам в эксплуатации оборудования.
Поэтому при унификации терминологии важно не просто свести все варианты к одному термину, а четко зафиксировать различия и привести их в глоссарий. Возможно, лучше указывать не просто «один и тот же объект», а группу устройств с разными принципами работы, но схожим назначением. Спасибо за точное замечание!