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