Comments 19
А статья грамотная, всё по полочкам разложено. Я бы назвал её списком требований к хорошему документу.
Полная документация может иметь внушительный размер. И на нескольких языках. Как поставлен процесс проверки, чтобы ничего не упустить, не забыть. Проверяете печатный документ или цифровой? Система контроля версий? Есть привязка к багтрекеру продукта? Что-то проверяется автоматизированно? Может какая-то CMS или "фреймворк" используется из которых компилируется документ?
- битые ссылки
- отсутствующие картинки
- наличие стоп-слов (жаргон, нецензурные слова)
- наличие неверных символов (н-р, русская буква «с» вместо англоязычной «c»)
- ошибки оформления (термины не выделены полужирным или предложение с маленькой буквы написали)
Ну и на что фантазии хватит. Но, конечно, такие вещи лучше проверять на исходниках документации (md, xml, html и т.д.), а не на скомпилированных документах.
В компании используем asciidoctor + uml (asciidoctor-diagram).
Исходники документации в git, сборка и версионирование средствами gradle (исторически сложилось, т.к. документацию изначально писали программисты; оказалось удобно), до этого был maven.
Сборка в pdf (также есть html, но мы его не используем), каждый файл получает в имени номер версии (во избежание путаницы у получателя).
Из приятных удобняшек — один исходник используется для двух сборок — одна xml-api, другая json (по сути различается примерами запросов-ответов). Используется условный оператор.
А за статью – спасибо!
Можно добавить:
- однородность. В том смысле, что если используются специальные термины — везде используются одни и те же, а не синонимы. Если есть стилистические приемы (например, куски xml-запросов или оформление кодов ошибок) — везде оформлены в одном стиле. Проблема особенно актуальна, когда документацию ведет несколько человек
- википедичный стиль изложения. В частности, изложение исключительно от третьего лица.
- список изменений, версия документа
- если речь идет о каких-либо интеграциях — всегда прилагать пример запросов-ответов или прочих вызовов. Это существенно упрощает понимание текста.
От себя добавлю, что для написания и требований и тестов и документации всегда использую еще одно золотое правило: «Всё, что МОЖЕТ быть неправильно понято — БУДЕТ неправильно понято!»
Ну и структурированность очень важна, да.
Тестирование документации к программным продуктам