Доброго времени суток.

Очень интересует вопрос организации процесса документирования разработки нового программного обеспечения (написания технической документации). Работаю в компании которая занимается написанием ПО для медицины (являюсь руководителем отдела), хотелось бы поднять уровень документирования систем у себя на более высокий уровень. Сейчас документирование выражено написанием комментариев в исходном коде программы и в БД (пакеты, функции). Нет единого документа который бы описывал все функции системы в полном объеме и давал понимание как взаимодествуют эти функции.

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

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

Изучая данную проблему я нашел описание структуры Modern SRS Package у Леффингуэлла. Документ мне в целом понравился... но мне кажется что он очень сложный и запутанный (и по этому документу есть ряд вопросов по его организации и заполнению). Использовал ли кто эту структуру для создания технической документации?

PS
Если я правильно понимаю то данный документ должен писаться всеми участниками проекта:
руководитель проекта - описывает бизнес логику, создает модели, фиксирует пользовательские и бизнес требования;
разработчики - описываю функции реализующие пользователькие требования, интерфейсы функций и взаимодествия между функциями

Есть стандартный набор документов, который поможет ориентироваться в системе:
1. Product Vision, оно же концепция
2. Software Requirements Specifcation, оно же требования к ПО
3. Software Architecture Document, оно же документ архитектуры ПО

Первый рассказывает о том, зачем продукт нужен, кому, какими ключевыми свойствами обладает
Второй рассказывает более детально, какими свойствами обладает продукт с точки зрения поведения и аспектов качества с внешней стороны, не залезая внутрь системы
Третий рассказывает, как оно устроено внутри — набор подсистем, модулей, ответственность каждого, взаимосвязи, порядок взаимодействия

Шаблоны 1-3 можно взять в RUP, примеры 1-2 — на сайте Вигерса, стандарты на 2-3: IEEE 830-1998, IEEE 1471

Процесс создания документов 1-2 описан в книгах Леффингуэлла и Вигерса, процесс создания документов 1-3 описан в RUP'e

Пример Software Architecture Document (разработчики для разработчиков): http://software-architecture.ru/examples/CM25_SAD.pdf

.... хотелось бы поднять уровень документирования систем у себя на более высокий уровень.....

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

Т.е.
1. Цель документа
2. Аудитория
3. Шаблон/наполнение

С ув., Саша

…создать правильный набор документов для унаследованных разработок - процесс достаточно трудоемкий.

Они же начинают новый проект — см. текст автора вопроса.

Очень интересует вопрос организации процесса документирования разработки нового программного обеспечения (написания технической документации).

PS
Если я правильно понимаю то данный документ должен писаться всеми участниками проекта:

А у Вас есть кто-то (из тех, кто есть прямо сейчас), кто способен при каких-то условиях, например, снижение загрузки, написать искомый документ? Как Вы могли бы этот процесс контролировать (читай - заставлять)?

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

К сожалению уровень разработчиков в документировании систем заканчивается расставлением комментариев в самых сложных участках кода.
У меня тоже не очень много опыта в плане организации работ по документированию систем. Прочитал книгу по урпавлению требованиями из нее почерпнул первые идеи о структуре и подходах.

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

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

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

Водолей идея с мозговм штурмом тоже имеет свой смысл. Из раззных методик и документов можно будет выбрать только то что нам действительно необходимо (то в чем мы будем видеть смысл при дальнейшей работе с документом)

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

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

Попробуйте применить внутреннюю контрактную приемку компонентов. То есть, руководитель проекта подписывает разработчику работу как сданную, только если выполнены все условия внутреннего "контракта", в котором, как и в настоящем контракте, прописаны требования к документации компонента. При этом разработчику выделяются ресурсы технического писателя, если он есть. Разработчик тогда заинтересован в том, чтобы плотно взаимодействовать с техническим писателем и подробно ему все объяснять.
РП заинтересован в том, чтобы проверить адекватность документации, т.к. это страховка его премии за проект на случай смены разработчика. "Контракт" является формальным документом для разбора неизбежных конфликтов.
Но трудозатраты и сроки увеличатся на  сколько-то (по ситуации) десятков процентов.

ПС. Наверное, это никак не стыкуется с концепцией Agile...

Задача стоит в том чтобы новый человек прочитал некий документ в которм бы ему стала понятна работа как всей системы в целом, так и ее компонентов в частности если это необходимо (например при исправлении ошибки или дописании новых функций в каком-то конкретном модуле).

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

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

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

P.S. В свое время мы использовали javadoc, который преобразует комментарии в исходном тексте в help-файлы. Можно начать с чего-то подобного.

P.S. В свое время мы использовали javadoc, который преобразует комментарии в исходном тексте в help-файлы. Можно начать с чего-то подобного.

doxygen

Но сами по себе, на чистой сознательности, программисты использовать его не будут. Нужно их, во-первых, убеждать (иногда металлической линейкой по рукам), а во-вторых, контролировать.

Но сами по себе, на чистой сознательности, программисты использовать его не будут. Нужно их, во-первых, убеждать (иногда металлической линейкой по рукам), а во-вторых, контролировать.

насколько я помню, никто подобного (про разбуженную сознательность) не утверждал :о))
и потом было интересно узнать про зависимость качества subj от силы убеждения (металлической линейкой по рукам)

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

Я хотел сказать немного другое. На момент разработки иметтся представление о том что делается как и зачем. Но вот дальше есть как минимум два возможных варианта:
1. програмист со временем сам забывает что он там делал, и что бы вникнуть ему надо время. Вникать приходится по двум причниам: доработка новым функционалом или исправление ошибки (которые часто должны быть решены еще вчера)
2. програмисты имеют свойство уходить... соответственно если другой разработчик садится на проект по одной из двух вышеописанных причин, он и представления о том что это за программа и как в ней что работает, и как там что править...
3. + еще возможна ситуация когда надо к проекту подключить человека, и дабы не дергать разработчика с вопросами а что тут и как, можно прочесть документ и спросить уж реально непонятное...

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

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

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

Тем не менее, ни один ребёнок ещё не научился ходить, опираясь на опыт предыдущих поколений.

Могу поделиться своим опытом, но не уверен, что он научит вас ходить. Перед нами стояла немного другая задача: разработать документацию к нашему API, которое мы передаём партнёрам для использования в их собственных разработках.


Во-первых, ввести правило: документировать все вновь разрабатываемые классы и функции (или на чём вы там пишете?) с помощью средств автоматического создания документации из исходных кодов - javadoc, если это Java, doxygen если это C/C++, или средства, встроенные в IDE (мы-то по старинке работаем, мэйком через командную строку). Здесь придётся предварительно выработать некоторые минимальные требования (для "C", например: описание задачи, выполняемой функцией, назначение и допустимые значения каждого параметра, перечень всех кодов возврата). Навязать команде такие правила "сверху" очень трудно. Единственный, на мой взгляд, работающий метод - вырабатывать эти требования совместно, всей командой, чтобы каждый был уверен, что это решение принято с его участием.


Во-вторых, разработать план такого же "низкоуровневого" документирования для того, что уже создано. Не стоит замахиваться на Вильяма нашего Шекспира сверхзадачу "задокументировать сразу всё". Начать с некоторых основных разделов, используемых всеми - тех исходников, в которые чаще всего приходится заглядывать для справки (опять же, например: подробное описание единых кодов возврата, иерархия и правила использования исключений и т. п.)
Ах, да... я, кажется, сказал "план"? Раз есть план, значит, его ещё нужно выполнять. Причём не "в фоновом режиме", а целенаправленно ставить задачи и выделять время на его реализацию.


В-третьих, для каждого модуля (или как это теперь называется?) создать страницу с его описанием. Мы это делаем с помощью того же doxygen, прямо в заголовочном файле модуля. Это уже не простой перечень функций, а некоторые "метаданные", базовое описание архитектуры - не очень объёмный текст, описывающий назначение модуля и содержащий примеры его использования. (Кстати, диаграмму классов doxygen создаёт автоматически).

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

Конечно, это тоже совершенно самостоятельная задача, и довольно трудоёмкая. Если реализовывать её "за счёт внутренних резервов", то, скорее всего, ничего не выйдет. Причём писать такие страницы лучше специально выделенному человеку, работающему в паре с разработчиком, который лучше всего этот модуль знает. ("Работать в паре" - значит, работать вдвоём, как принято в XP, которое не Windows, а экстремальное программирование.)

Почему я поставил это "в-третьих", если это самая важная часть документации? Возможно, потому что именно в таком порядке это происходило у нас. Первый шаг, с одной стороны, сделать довольно легко, при этом он служит чем-то вроде индикатора, показывающего решимость команды поменять своё отношение к документации. Но именно за его исполнением нужно неукоснительно следить: энтузиазм быстро угасает, а если у разработчика появляется какая-то срочная задача, он легко переключается в режим "некогда романы писать, кодить надо", в котором и остаётся. Тогда приходится всё начинать сначала.


У нас в результате выполнения этих трёх шагов получилась вполне пригодная для использования документация в формате Windows Help (мы даже когда-то интегрировали её в MS Visual Studio). Мы сами её используем как справочник, а страницы, получившиеся на третьем шаге, я несколько лет достаточно успешно использовал как материал для обучения партнёров: там есть и описание реализованных концепций, и примеры использования кода.

Но этого для нашей задачи оказалось недостаточно: всё равно у партнёров после обучения возникало много вопросов, нужно было несколько месяцев использования API в реальной разработке, пока этот паззл из описания отдельных модулей не складывался в цельную картинку. И тогда пришлось написать ещё один документ, уже не привязанный к исходным кодам - Developers Guide, описывающий пошаговый процесс создания приложения с использованием нашего API, начиная с пустого шаблона (аналог "Hello World") с постепенным подключением модулей - файловой системы, загрузки параметров, подключения коммуникаций, печати чеков и т. д.

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


По поводу шаблонов тоже скажу пару слов. Я тоже начинал (а кто начинал иначе? пусть первым в меня плюнет!) с поиска неких "универсальных шаблонов" для документации. Причём во всех областях, связанных с разработкой ПО - начиная с шаблона ТЗ (ага, мне уже не стыдно в этом признаваться ) и заканчивая "рыбой" функциональных обязанностей. Мой личный вывод: все эти шаблоны хороши для общего расширения кругозора (подсказывают, "куда копать"), но оказываются абсолютно неприменимыми для наших конкретных проектов. imho нужно не найти шаблон документа и пытаться подогнать под него процессы, выполняемые командой, а наоборот, сначала формализовать и упорядочить процессы, а тогда уже естественным образом появится шаблон, который будет развиваться и дополняться согласованно с изменением и улучшением процесса.


(Посмотрел через "Предварительный просмотр" и ужаснулся: какой длиннющий пост получился! Надо будет его причесать и вставить в блог.)

Тем не менее, ни один ребёнок ещё не научился ходить, опираясь на опыт предыдущих поколений.

Почему? Ребенок видит, что другие ходят на ногах и сам начинает.
Если бы кругом все ходили на руках, то и он бы на руках стал ходить.