в облаке
Попробовать

Мотивация для написания справочной документации

Ни для кого не секрет, что справочная документация к программному продукту является необходимым элементом эффективного его использования. Однако, зачастую, разработчики ПО не уделяют времени на написание документации к своей разработке. На мой взгляд причин тому несколько:

  • Непосильный объем работы - если изо дня в день откладывать написание документации или ее обновление, то к моменту завершения работ над очередной версией вам потребуется потратить уйму времени на эту задачу, в общем-то не самую интересную. Решением данной проблемы является постоянное внесение изменений в документацию по мере развития или изменения функционала.
  • Отсутствие подходящего инструмента - профессиональные инструменты подготовки файлов справки достаточно дороги, а современные технологии отображения файлов справки базируются на формате HTML, который требует ручной работы для подгонки справки под каждый новый инструмент.
  • Поддержка нескольких форматов - изначально сложно определиться с тем инструментом, который будет использован для формирования конечного справочного файла, и более того, вам может потребоваться ни раз его поменять. Написав документацию один раз в формате MSWord в будущем вам придется перевести ее в другие форматы и чаще всего вручную.

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

Создание справочной документации заключается в редактировании Wiki страниц, где вы, используя простую разметку, определяете содержимое и внешний вид будущей справочной документации. Теперь вы не зависите от форматов, поскольку Wiki может быть выгружена в произвольный формат: HTML, MSWord и другие. Ваша документация теперь не зависит от стиля, что достигается заданием вашего собственного стиля при выгрузке документации в формат HTML.

В настройках методологии вашего проекта включите опцию "Использование фазы подготовки справочной документации", после чего при планировании каждого пожелания DEVPROM будет автоматически предлагать создать задачу по написанию документации. На этапе планирования вы уже задумываетесь о доработке справочной документации. Теперь задача по написанию документации делится на множество мелких задач, которые могут выполнять несколько человек.

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

Еще интересные статьи на эту тему: