Я лично люблю писать документацию. Мне доставляет удовольствие описывать отдельные элементы системы точным, точным и понятным для получателя способом. Ниже я представляю сборник советов и комментариев, которые, надеюсь, будут полезны как тем, кто пишет «от сердца», так и тем, для кого это неприятная обязанность, а так же рассказываю где я распечатываю документацию проекта
Я представляю свои комментарии в виде коротких абзацев, касающихся конкретных вопросов, связанных с написанием документации. Я разработал их, основываясь на собственном опыте и прочитав несколько книг, названия которых указаны в конце.
Особенности хорошей документации:
- это точно и безошибочно,
- завершено,
- согласуется,
- написано четко и недвусмысленно,
- пользователь может легко найти нужную ему информацию,
- имеет аккуратный, приятный внешний вид.
Этапы создания документации:
- сбор информации об описываемой системе,
- создание проекта документации,
- написание документации,
- проверка документации,
- внесение исправлений и заполнение пробелов.
Последние два шага обычно повторяются несколько раз, пока не будут устранены все неисправности.
Информация об описываемой системе может быть собрана посредством:
- чтение уже существующих фрагментов документации,
- работа с программой и анализ исходного кода,
- консультации (обычно с разработчиками, создавшими систему).
Проект документации должен содержать следующие элементы:
- название документации,
- тип документации (например, руководство пользователя),
- предполагаемая дата завершения работы над документацией,
- имя и фамилия режиссера-документалиста,
- краткое описание того, что будет содержать документация,
- предполагаемое количество страниц (это лучше всего определить, сравнив с аналогичными существующими документами),
- список основных глав,
- контрольные сроки.
Вехой в написании документации является момент, когда документация передается на проверку. Хорошее место для установки вашей первой вехи , когда:
- большая часть (две трети или три четверти) текста уже написана,
- отмечены места, куда будут вставляться рисунки и скриншоты.
Хорошее место для установки второй вехи , когда:
- практически весь текст уже написан,
- почти все рисунки и скриншоты уже есть в документации,
- Дефекты, выявленные в ходе проверки после первого этапа, были исправлены.
При создании документации обычно есть как минимум две вехи, а часто и не больше. Поэтому в черновой документации чаще всего указывают даты двух камней.
Проверка документов означает:
- внимательно читайте документацию на наличие ошибок,
- проверка соответствия скриншотов тому, что реально видно на экране в описываемый момент,
- выполнение процедур (инструкций), содержащихся в документации, и проверка того, действительно ли они приводят к желаемым результатам,
- передача документации рецензентам и сбор их комментариев.
Полезный метод проверки — также попросить кого-то, кто не слишком хорошо разбирается в описываемой системе, прочитать документацию и убедиться, что он все понял. Причина: документалист может забыть написать то, что для него «очевидно», а рецензент, обычно знакомый с системой, такой недостаток может не заметить.