How to become an author
Search
Write a publication
Pull to refresh

Comments 19

Из-за названия статьи я сначала подумал, что вы какое-то автоматическое тестирование настроили.
А статья грамотная, всё по полочкам разложено. Я бы назвал её списком требований к хорошему документу.
Total votes 3: ↑3 and ↓0+3

Полная документация может иметь внушительный размер. И на нескольких языках. Как поставлен процесс проверки, чтобы ничего не упустить, не забыть. Проверяете печатный документ или цифровой? Система контроля версий? Есть привязка к багтрекеру продукта? Что-то проверяется автоматизированно? Может какая-то CMS или "фреймворк" используется из которых компилируется документ?

Total votes 1: ↑1 and ↓0+1
Проверяется цифровой документ. Автоматизировать по-хорошему тут можно только проверку орфографии. Разумеется, есть автоматизированная система, в которой ведется работа над документацией, но пользоваться мне ей не доводилось, могу лишь сказать что все очень хорошо организовано.
This comment wasn’t rated yet0
А назвать можете? Или это внутренняя разработка?
This comment wasn’t rated yet0
К сожалению, не готов назвать (чту договор с работодателем о неразглашении информации о компании).
This comment wasn’t rated yet0
Можно автоматизировать проверку на вот такие косяки:

  • битые ссылки
  • отсутствующие картинки
  • наличие стоп-слов (жаргон, нецензурные слова)
  • наличие неверных символов (н-р, русская буква «с» вместо англоязычной «c»)
  • ошибки оформления (термины не выделены полужирным или предложение с маленькой буквы написали)

Ну и на что фантазии хватит. Но, конечно, такие вещи лучше проверять на исходниках документации (md, xml, html и т.д.), а не на скомпилированных документах.
This comment wasn’t rated yet0
Полезное правило в документации: за деепричастный оборот расстрел на месте, предложение с тремя запятыми и более — штраф или объяснительная. Вообще, писать надо как для слегка умственно отсталого. Лучше повториться, чем допустить неясность. Вообще, красота текста документации — зло, требуется невозможность неправильного толкования.
Total votes 1: ↑1 and ↓0+1
Господи как же я раньше-то читал документацию с деепричастными оборотами, и тремя и более запятыми! Спасибо, что просвятили. Больше не буду такого делать.
Total votes 1: ↑1 and ↓0+1
Читать можно, но использовать деепричастный оборот в технической документации не желательно.
This comment wasn’t rated yet0
А какие-то инструменты ведения документации можете оценить на базе своего опыта? Очень интересно.
This comment wasn’t rated yet0
Неа, инструментами ведения документации пользоваться не доводилось. Лишь тестировал качество.
This comment wasn’t rated yet0

В компании используем asciidoctor + uml (asciidoctor-diagram).
Исходники документации в git, сборка и версионирование средствами gradle (исторически сложилось, т.к. документацию изначально писали программисты; оказалось удобно), до этого был maven.
Сборка в pdf (также есть html, но мы его не используем), каждый файл получает в имени номер версии (во избежание путаницы у получателя).
Из приятных удобняшек — один исходник используется для двух сборок — одна xml-api, другая json (по сути различается примерами запросов-ответов). Используется условный оператор.

Total votes 2: ↑2 and ↓0+2
Большое спасибо, что поделились — как выяснилось, такой инструмент, как asciidoctor, прошёл мимо меня. Лень, конечно, заморачиваться с Ruby, ибо это совершенно чужой для меня инструмент, но надо попробовать. Возможно, сборка в PDF и HTML одновременно + читабельность исходных файлов того стоят.
This comment wasn’t rated yet0
Спасибо за статью: подробно, лаконично, легко проверять свои тексты при подготовке пакета документации по такому чек-листу!
Total votes 1: ↑1 and ↓0+1
По поводу качества документации я для себя решил за «точку отсчета» взять ГОСТы класса 19 (ЕСПД – Единая Система Программной Документации) и уже от неё «работать напильником». Где-то больше, где-то меньше – в зависимости от требований заказчика (для конечных пользователей – один вариант, для ИТ-специалистов – расширенный вариант).
А за статью – спасибо!
Total votes 1: ↑1 and ↓0+1
Это хорошо когда за документацию отвечают специально обученные (с отдельным ФОТ) люди. Бывает разработчики ПО пишут документацию по ГОСТ, ведущие специалисты проверяют/тестируют, затем руководители проверяют/тестируют, затем заказчик. Это такой отдельный Ад по превращению разработчиков в «Программистов Word за 3 года», не надо так.
This comment wasn’t rated yet0

Можно добавить:


  • однородность. В том смысле, что если используются специальные термины — везде используются одни и те же, а не синонимы. Если есть стилистические приемы (например, куски xml-запросов или оформление кодов ошибок) — везде оформлены в одном стиле. Проблема особенно актуальна, когда документацию ведет несколько человек
  • википедичный стиль изложения. В частности, изложение исключительно от третьего лица.
  • список изменений, версия документа
  • если речь идет о каких-либо интеграциях — всегда прилагать пример запросов-ответов или прочих вызовов. Это существенно упрощает понимание текста.
Total votes 1: ↑1 and ↓0+1
Здорово, эти же принципы можно и к любой документации приложить (например, которая пишется тестировщиками для тестировщиков).
This comment wasn’t rated yet0
За статью — риспект.
От себя добавлю, что для написания и требований и тестов и документации всегда использую еще одно золотое правило: «Всё, что МОЖЕТ быть неправильно понято — БУДЕТ неправильно понято!»
Ну и структурированность очень важна, да.
This comment wasn’t rated yet0
Sign up to leave a comment.

Articles

Show the best of all time

Your account

Sections

Information

Services

Support
© 2006–2024, Habr