Документирование - финальный этап процесса разработки. Если хочется общей картины, то вот как это выглядит в типичном случае:

1. Заказ. Клиент заказывает проект, незная примерно чего он хочет.
2. Предложение. Компания хвалится что уже делала много подобных проектов и спрашивает детали и плавно переходит к заключению договора.
3. Разработка
   1. Анализ - много беседы с клиентом что-бы понять его ситуацию и его нужды
   2. Дизайн - проектирование на высоком уровне БД и оценка необходимых задач
   3. Кодинг
   4. Тестирование (Quality Assurance)
   5. Документирование
4. Поддержка (Support)
5. Оценка квалитета

Цель документации в предоставлении детальной информации о продукте/системе. Если в анализе рассматривались абстрактные пользователи, процессы, связи, то в документации всё чётко.

Документирование интерфейса или user's manual

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

1. MS Office + Adobe Acrobat
2. WikiPad, media wiki
   
3. MS OneNote

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

Документирование кода

Если wiki ещё может быть полезным программистам, то Office Word - наврядли. Всё дело в неудобном оглавлении, необходимости кроссылочности и связями с кодом. Поэтому для документирования кода используют программы-генераторы, сканирующие файлы проекта в поиске комментариев. Если же комментариев нет, а как работает система вы не знаете то прийдётся заняться неприятной работой reverse-engineering'а.

Многие IDE (Zend, Visual Studio, Netbeans) уже включают в себя средства документирования, но никакого общего стандарта до сих пор нет. В своём большинстве, цель генераторов - составить нечто типа энциклопедии всех функций, классов, объектов, иерархий классов, связей между файлами, используемые компоненты и третьи программные продукты. Вся эта огромная информация редко когда может быть полезна начинающему программисту, которому в действительности сначала нужны UML схемы общей архитектуры:

• Логические разделы или то что видет пользователь (use case, интерфейс, цель инфосистемы)
• Общий вид потока информации (связь с БД, темплейты, сервисы, глобальные объекты)
• Соответсвие логическим разделам физическим файлам и таблицам БД (модульность платформы)

Генераторы можно условно разделить на:

• Универсальные
  
  • Doxygen для C, Java, Python, PHP. На выходе - html, pdf, man, pdf, rtf.
  • NaturalDocs
  • AsciDoc
  • doc-o-matic для Matlab, ASPX, JSP, IDL, Delphi, C#, VB, Java, PHP
• Специфичные
  
  • javadoc для Java
  • phpDocumentor для PHP
  • docutils
  • NDoc, Sandcastle, GhostDoc для .NET
  • pasdoc для Delphi
  • ZenDoc для ActionScript

Генераторы как правило по-своему хранят данные и комментарии, завися от языка, однако последние тенденции например в Visual Studio показывают популяризацию xml. DocBook - одна их предлагаемых универсальных схем.

Читайте также:

• Техническое задание (ТЗ)
• Процесс документирования
• Почему при гибких методах разработки (agile development) документация ведётся редко