Как правильно оформить документацию

Написание документации часто рассматривается программистами как тяжкое наказание и божественное деяние. Руководители проектов чуть больше в этом разбираются, особенно те, кто однажды потерял сотрудника, который был «гуру системы/программы/модуля» посреди проекта и должен был внезапно ставить на работу нового человека, прогрызая тысячи строк недокументирован и часто кодируется без комментариев.

Я лично люблю писать документацию. Мне доставляет удовольствие описывать отдельные элементы системы точным, точным и понятным для получателя способом. Ниже я представляю сборник советов и комментариев, которые, надеюсь, будут полезны как тем, кто пишет «от сердца», так и тем, для кого это неприятная обязанность, а так же рассказываю где я распечатываю документацию проекта 

Я представляю свои комментарии в виде коротких абзацев, касающихся конкретных вопросов, связанных с написанием документации. Я разработал их, основываясь на собственном опыте и прочитав несколько книг, названия которых указаны в конце.

Особенности хорошей документации:

  • это точно и безошибочно,
  • завершено,
  • согласуется,
  • написано четко и недвусмысленно,
  • пользователь может легко найти нужную ему информацию,
  • имеет аккуратный, приятный внешний вид.

Этапы создания документации:

  • сбор информации об описываемой системе,
  • создание проекта документации,
  • написание документации,
  • проверка документации,
  • внесение исправлений и заполнение пробелов.

Последние два шага обычно повторяются несколько раз, пока не будут устранены все неисправности.

Информация об описываемой системе может быть собрана посредством:

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

Проект документации должен содержать следующие элементы:

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

Вехой в написании документации является момент, когда документация передается на проверку. Хорошее место для установки вашей первой вехи , когда:

  • большая часть (две трети или три четверти) текста уже написана,
  • отмечены места, куда будут вставляться рисунки и скриншоты.

Хорошее место для установки второй вехи , когда:

  • практически весь текст уже написан,
  • почти все рисунки и скриншоты уже есть в документации,
  • Дефекты, выявленные в ходе проверки после первого этапа, были исправлены.

При создании документации обычно есть как минимум две вехи, а часто и не больше. Поэтому в черновой документации чаще всего указывают даты двух камней.

Проверка документов означает:

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

Полезный метод проверки — также попросить кого-то, кто не слишком хорошо разбирается в описываемой системе, прочитать документацию и убедиться, что он все понял. Причина: документалист может забыть написать то, что для него «очевидно», а рецензент, обычно знакомый с системой, такой недостаток может не заметить.

Оставьте ответ

Ваш адрес email не будет опубликован.