хочется просто пропустить пару детских шагов, опыт других поколений ведь не зря скапливается. ![Улыбающийся :)](http://www.uml2.ru/forum/Smileys/classic/smiley.gif)
Тем не менее, ни один ребёнок ещё не научился ходить, опираясь на опыт предыдущих поколений.
![Улыбающийся :)](http://www.uml2.ru/forum/Smileys/classic/smiley.gif)
Могу поделиться своим опытом, но не уверен, что он научит вас ходить. Перед нами стояла немного другая задача: разработать документацию к нашему API, которое мы передаём партнёрам для использования в их собственных разработках.
Во-первых, ввести правило: документировать все вновь разрабатываемые классы и функции (или на чём вы там пишете?) с помощью средств автоматического создания документации из исходных кодов - javadoc, если это Java, doxygen если это C/C++, или средства, встроенные в IDE (мы-то по старинке работаем, мэйком через командную строку). Здесь придётся предварительно выработать некоторые минимальные требования (для "C", например: описание задачи, выполняемой функцией, назначение и допустимые значения каждого параметра, перечень всех кодов возврата). Навязать команде такие правила "сверху" очень трудно. Единственный, на мой взгляд, работающий метод - вырабатывать эти требования совместно, всей командой, чтобы каждый был уверен, что это решение принято с его участием.
Во-вторых, разработать план такого же "низкоуровневого" документирования для того, что уже создано. Не стоит замахиваться на
Вильяма нашего Шекспира сверхзадачу "задокументировать сразу всё". Начать с некоторых основных разделов, используемых всеми - тех исходников, в которые чаще всего приходится заглядывать для справки (опять же, например: подробное описание единых кодов возврата, иерархия и правила использования исключений и т. п.)
Ах, да... я, кажется, сказал "план"? Раз есть план, значит, его ещё нужно выполнять.
![Улыбающийся :)](http://www.uml2.ru/forum/Smileys/classic/smiley.gif)
Причём не "в фоновом режиме", а целенаправленно ставить задачи и выделять время на его реализацию.
В-третьих, для каждого модуля (или как это теперь называется?) создать страницу с его описанием. Мы это делаем с помощью того же doxygen, прямо в заголовочном файле модуля. Это уже не простой перечень функций, а некоторые "метаданные", базовое описание архитектуры - не очень объёмный текст, описывающий назначение модуля и содержащий примеры его использования. (Кстати, диаграмму классов doxygen создаёт автоматически).
Здесь, опять же, без плана не обойтись. Нужно определить порядок документирования модулей согласно какой-то системе приоритетов (важность, сложность, частота использования и т. п. - для нас высший приоритет имели те модули, по которым возникало больше всего вопросов у наших партнёров). Это, пожалуй, самая важная часть той документации, которая генерируется из исходных текстов. В работе любого отдельно взятого класса или функции разобраться не так уж и сложно (если там не
индусский код, конечно), а вот охват "с высоты птичьего полёта" - это как раз то, ради чего документация и создаётся.
Конечно, это тоже совершенно самостоятельная задача, и довольно трудоёмкая. Если реализовывать её "за счёт внутренних резервов", то, скорее всего, ничего не выйдет. Причём писать такие страницы лучше специально выделенному человеку, работающему в паре с разработчиком, который лучше всего этот модуль знает. ("Работать в паре" - значит, работать вдвоём, как принято в XP, которое не Windows, а
экстремальное программирование.)
Почему я поставил это "в-третьих", если это самая важная часть документации? Возможно, потому что именно в таком порядке это происходило у нас. Первый шаг, с одной стороны, сделать довольно легко, при этом он служит чем-то вроде индикатора, показывающего решимость команды поменять своё отношение к документации. Но именно за его исполнением нужно неукоснительно следить: энтузиазм быстро угасает, а если у разработчика появляется какая-то срочная задача, он легко переключается в режим "некогда романы писать, кодить надо", в котором и остаётся. Тогда приходится всё начинать сначала.
У нас в результате выполнения этих трёх шагов получилась вполне пригодная для использования документация в формате Windows Help (мы даже когда-то интегрировали её в MS Visual Studio). Мы сами её используем как справочник, а страницы, получившиеся на третьем шаге, я несколько лет достаточно успешно использовал как материал для обучения партнёров: там есть и описание реализованных концепций, и примеры использования кода.
Но этого для нашей задачи оказалось недостаточно: всё равно у партнёров после обучения возникало много вопросов, нужно было несколько месяцев использования API в реальной разработке, пока этот паззл из описания отдельных модулей не складывался в цельную картинку. И тогда пришлось написать ещё один документ, уже не привязанный к исходным кодам - Developers Guide, описывающий пошаговый процесс создания приложения с использованием нашего API, начиная с пустого шаблона (аналог "Hello World") с постепенным подключением модулей - файловой системы, загрузки параметров, подключения коммуникаций, печати чеков и т. д.
В вашем случае, если возникнет необходимость разработки таких документов, нужно достаточно чётко определить, для кого этот документ может быть предназначен и какие проблемы он поможет решить (что, впрочем, справедливо вообще для любого разрабатываемого документа).
По поводу шаблонов тоже скажу пару слов. Я тоже начинал (а кто начинал иначе? пусть первым в меня плюнет!) с поиска неких "универсальных шаблонов" для документации. Причём во всех областях, связанных с разработкой ПО - начиная с шаблона ТЗ (ага, мне уже не стыдно в этом признаваться
![Подмигивающий ;)](http://www.uml2.ru/forum/Smileys/classic/wink.gif)
) и заканчивая "рыбой" функциональных обязанностей. Мой личный вывод: все эти шаблоны хороши для общего расширения кругозора (подсказывают, "куда копать"), но оказываются абсолютно неприменимыми для наших конкретных проектов. imho нужно не найти шаблон документа и пытаться подогнать под него процессы, выполняемые командой, а наоборот, сначала формализовать и упорядочить процессы, а тогда уже естественным образом появится шаблон, который будет развиваться и дополняться согласованно с изменением и улучшением процесса.
(Посмотрел через "Предварительный просмотр" и ужаснулся: какой длиннющий пост получился! Надо будет его причесать и вставить в блог.)