Интересуют два вопроса:

1. какого рода документацию вы пишете на разрабатываемое ПО ? (uml-диаграммы, справочник по функциям, руководство пользователя...)

2. какими программами пользуетесь при ее оформлении ? (West Wind HTML Help Builder и т.д.)

3. какой вид документации чаще используется ?

4. Есть ли где-нибудь статья, где бы научно-популярно объяснялись разные виды документации и где они применяются.

Я так как недавний выпускник с этой областью пока мало сталкивался, то почитаю любые ваши комментарии на эту тему

Здравствуйте, Саша Равный, Вы писали:

СР>1. какого рода документацию вы пишете на разрабатываемое ПО ? (uml-диаграммы, справочник по функциям, руководство пользователя...)
Я лично, как программист, делаю схемы БД и диаграммы классов, также пишу комменты (на основе них в некотрых языках документация можно сгенерить специальными утилитами).
Руководство пользователя пигут технические писатели — они, в отличии от программистов, умеют нормальным человеческим языком описать программу

СР>2. какими программами пользуетесь при ее оформлении ? (West Wind HTML Help Builder и т.д.)
Разными, какая под рукой будет и какая удобнее.

СР>3. какой вид документации чаще используется ?
Комментарии

СР>4. Есть ли где-нибудь статья, где бы научно-популярно объяснялись разные виды документации и где они применяются.
Почитай описания различных методологий разработки, там, как правило, приводится список документов, которые должны быть составлены в течение разработки продукта.

Здравствуйте, Саша Равный, Вы писали:

СР>Интересуют два вопроса:

какие два из четырёх?

СР>1. какого рода документацию вы пишете на разрабатываемое ПО ? (uml-диаграммы, справочник по функциям, руководство пользователя...)

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

СР>2. какими программами пользуетесь при ее оформлении ? (West Wind HTML Help Builder и т.д.)

open office writer, для uml — до сих пор пользуюсь borland together community, для которого когда-то удалось запросить бесплатную лицензию, впрочем, картинки, всё равно, компонуются в документах open office

СР>3. какой вид документации чаще используется ?

комментарии в коде и настроечных файлах, doc и его openoffice-ный аналог, pdf

СР>4. Есть ли где-нибудь статья, где бы научно-популярно объяснялись разные виды документации и где они применяются.

хз, всё равно, приходится делать как просит заказчик

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

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

Теперь то, что удается делать лишь в том случае, если на это выделяется время.
Литературное описание проекта в отдельном документе. Начиная с высоты птичьего полета (постановка задачи, идеология, архитектура), и постепенно спускаясь к грубой детализации. Т.е. литературному описанию взаимосвязей модулей и разъяснению работы сложных алгоритмов. Именно литературному описанию (не более того, т.к. детали есть в коде и комментах к нему, которые могут меняться). Именно такого описания как правило не хватает, когда приходит новый человек на проект, чтобы ввести его в курс дела. Есть умники, которые говорят — "Мой код прокомментирован, чего еще надо?". Некоторые даже пытаются отмазаться, сгенерировав документацию по XML комментам. Или сгенерив схему классов средствами студии. И называют это документацией. Ну тут опять рука к пистолету, и т.п. . Вроде бы все это настолько очевидно (что нужно литературное описание), что думаю — зачем я все это пишу? Но просто убедился на практике в том, что огромное количество народа не считают это необходимым. Наверно, это в большинстве своем гениальные люди.
Должно быть также описание таблиц базы — зачем нужна каждая таблица и каждое поле в ней. Описания хранимок можно думаю делать в комментах к самим хранимкам.
Инструкция по развертыванию системы.
Для этого я лично юзаю Innovasys HelpStudio.

Здравствуйте, sunshine, Вы писали:

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

Здравствуйте, Tissot, Вы писали:

T>Здравствуйте, sunshine, Вы писали:

T>Вы написали много правильных и хороших слов, но так и не уточнили, зачем вы это делаете.

Что зачем делаю — правильные слова пишу или доки и комменты?
Если последнее, то вот зачем:
1. Вот представьте — приходит новый человек на проект. Если нет документа, где литературно описана архитектура, идеология ну и все прочее, что я упомянул, то все это придется ему объяснять словами. Ну ладно, допустим, один раз можно еще объяснить кому-то. Но одним разом дело как правило не ограничивается. Допустим, чел свалил, нанимаем другого. Ну или берем дополнительного. Или скажем вы человеку что-то объяснили, а он забыл. Чувствуете, что уже дело идет к тому, что превращаешься в магнитофон? Одно дело дать читать доки, или в крайнем случае указать место, в котором есть ответ на его вопрос, другое дело как попка это все сто раз повторять.
2. Допустим, сваливаете вы сами. Наличие таких литературных доков очень сильно уменьшает количество телефонных переговоров, которые инициирует ваш преемник спрашивая то одно, то другое.

Вообще конечно все это ужасно банально и очевидно. Вот только действительность такова, что это мало кто делает.

Здравствуйте, sunshine, Вы писали:

S>Вообще конечно все это ужасно банально и очевидно. Вот только действительность такова, что это мало кто делает.

Может эти "кто" более адекватно оценивают издержки на поддержку всей этой литературы?

Здравствуйте, Tissot, Вы писали:

T>Здравствуйте, sunshine, Вы писали:

S>>Вообще конечно все это ужасно банально и очевидно. Вот только действительность такова, что это мало кто делает.

T>Может эти "кто" более адекватно оценивают издержки на поддержку всей этой литературы?

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

Здравствуйте, Саша Равный, Вы писали:
..

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

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

3 Руководство пользователя.
Должно понятным языком описывать способы получения заявленной для продукта функциональности.

Опционально (в зависимости от типа, сложности продукта, процессов, принятых в компании) — детальный дизайн (тот самый UML), макет UI (если UI имеется и т.п.

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

Одним из способов исключения документации дизайна (и поддержания его ап-ту-дейт) является подход Executable Models который подразумевает, что дизайн системы, описанный специальным образом, становится ее каркасом. При этом изменения в дизайне автоматически отражаются в продукте.

Здравствуйте, sunshine, Вы писали:

S>Префиксы с обозначением типа в названиях переменных. Когда слышу как кто-то говорит, что "зачем префиксы, можно ведь мышку навести и узнаешь, какой у нее тип", рука тянется к пистолету.
Тебе предупредительный выстрел в живот.

Здравствуйте, sunshine, Вы писали:

S>>>Вообще конечно все это ужасно банально и очевидно. Вот только действительность такова, что это мало кто делает.

T>>Может эти "кто" более адекватно оценивают издержки на поддержку всей этой литературы?

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

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

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

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

Здравствуйте, CreatorCray, Вы писали:

CC>Здравствуйте, sunshine, Вы писали:

S>>Префиксы с обозначением типа в названиях переменных. Когда слышу как кто-то говорит, что "зачем префиксы, можно ведь мышку навести и узнаешь, какой у нее тип", рука тянется к пистолету.
CC>Тебе предупредительный выстрел в живот.

Не принимай близко к сердцу. Скажи лучше по теме что-нибудь.

Здравствуйте, Саша Равный, Вы писали:

СР>Я так как недавний выпускник с этой областью пока мало сталкивался, то почитаю любые ваши комментарии на эту тему

Посамопиарюсь немножко: What do you need to know.

Здравствуйте, sunshine, Вы писали:


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

S>Поэтому в таких доках не нужно вдаваться в подробности. Их смысл — в так сказать метаинформации о проекте.

ИМХО толковая и понятная архитектура заруливает эту мегадоку по эффективности и стоимости, а понятный и хорошо структурированный код, выдержанный по соглашениям о кодировании заруливает любые каменты. Все доки надо поддерживать, если что то меняется — меняем в в коде и литературе. Часто наблюдал — в доках/камментах писано одно, по коду — все наоборот. Понимания не прибавляло.

MNN>ИМХО толковая и понятная архитектура заруливает эту мегадоку по эффективности и стоимости, а понятный и хорошо структурированный код, выдержанный по соглашениям о кодировании заруливает любые каменты. Все доки надо поддерживать, если что то меняется — меняем в в коде и литературе. Часто наблюдал — в доках/камментах писано одно, по коду — все наоборот. Понимания не прибавляло.

Дай Бог, дай Бог...
Что-ж, я тоже хочу попасть в такую страну, где проекты толковые и понятные, и код тоже спльшь понятный и хорошо структурированный... И все это настолько хорошо, толково, понятно и структурировано, что новые сотрудники въезжают в курс дела даже без доков и комментов... Страна обетованная! Когда обрету тебя?

Здравствуйте, sunshine, Вы писали:

S>Что-ж, я тоже хочу попасть в такую страну, где проекты толковые и понятные, и код тоже спльшь понятный и хорошо структурированный...

Это не от страны зависит.

S> И все это настолько хорошо, толково, понятно и структурировано, что новые сотрудники въезжают в курс дела даже без доков и комментов... Страна обетованная! Когда обрету тебя?

Когда подкопишь толику экспириенса, и немножко шире взглянешь на процесс разработки, имхо.

AVK>Когда подкопишь толику экспириенса, и немножко шире взглянешь на процесс разработки, имхо.

Хорошо. Тогда позволь взглянуть, как это делается у корифеев .
Вот есть у тебя сложный проект. Наняли нового сотрудника для доработки функционала и поддержки. Пришел он, сел за комп. Ты ему показываешь, откуда загрузить проект, он его загружает, и... Дальше что? Он сидит и молча смотрит код проекта в студии? Или все-таки задает вопросы по ходу? Если все-таки задает вопросы, то не обращал-ли ты внимание — сколько примерно времени уходит в общей сложности на устные объяснения, прежде чем он овладеет кодом настолько, что будет способен делать сколько-нибудь значительные доработки?

Здравствуйте, sunshine, Вы писали:

AVK>>Когда подкопишь толику экспириенса, и немножко шире взглянешь на процесс разработки, имхо.

S>Хорошо. Тогда позволь взглянуть, как это делается у корифеев .

Ежедневные митинги, на которых обсуждается вопросы "что делать", "как делать", "как уже сделано" по аналогии, с участием ветеранов и новичков. Парная работа с ветеранам, которые походу объясняют тонкости проекта.

S>Вот есть у тебя сложный проект. Наняли нового сотрудника для доработки функционала и поддержки.

На проекте один сотрудник ? Или какая то команда разработчиков ?

S>Пришел он, сел за комп. Ты ему показываешь, откуда загрузить проект, он его загружает, и... Дальше что? Он сидит и молча смотрит код проекта в студии? Или все-таки задает вопросы по ходу? Если все-таки задает вопросы, то не обращал-ли ты внимание — сколько примерно времени уходит в общей сложности на устные объяснения, прежде чем он овладеет кодом настолько, что будет способен делать сколько-нибудь значительные доработки?

Вопросы будут задавать всегда, тут доками не отмажешься, кроме того, что прочитать, наде еще понять прочитанное, что не всегда и возможно. Время полноценного вхождения нового девелопера в проект зависит от квалификации и способности его читать чужой код. Для нормального — примерно месяц. Но месяц не читки документации, а интенсивной итерактивной работы.

MNN>На проекте один сотрудник ? Или какая то команда разработчиков ?
Несколько человек. Но вообще думаю к текущему обсуждению это не особенно относится, т.к. тема более общая, что-ли.

MNN>Ежедневные митинги, на которых обсуждается вопросы "что делать", "как делать", "как уже сделано" по аналогии, с участием ветеранов и новичков.
Ежедневные, имхо, как-то уж чересчур, но судить не берусь.

MNN>Вопросы будут задавать всегда, тут доками не отмажешься
Дык, о полной отмазке речь и не идет.
Речь идет о том, что если есть док (хочу подчеркнуть, не МЕГАдок, а такой, который можно за день, максимум за два прочитать), то у человека уже через день-два будет в голове целостное представление о проекте (даже без единого устного вопроса). После этого он уже может вникать конкретно в свой кусок, читая код.
Конечно, будут вопросы и интерактивная работа с ветеранами. Однако, это будут уже гораздо более специфические, уточняющие вопросы.

MNN>Парная работа с ветеранами, которые походу объясняют тонкости проекта.
Вот именно, ветеранов надо беречь , т.е. пусть они объясняют именно тонкости проекта, а не общие вещи (причем время затраченное на объяснение общих вещей умножаем на количество новичков). Я уж не говорю о том, что действует на нервы проговаривать одно и то же разным людям. Хочется как-то это оптимизировать.
Ну ладно, пусть все замечательно структурировано, толково, и т.п. И все-таки человек задает некий общий вопрос. Как поступите? Наверно, все-таки станете объяснять. Все-таки тыкать чела носом в проект с предложением разбираться самому как-то невежливо . Мне лично представляется, что такое происходит достаточно часто для того, чтобы имело смысл выразить это письменно. И набор этих общих вопросов, которые новички все равно задают, несмотря на отличную архитектуру, структурированность и т.п., примерно одинаков.

Хочу подчеркнуть, что я такой док не позиционирую как необходимость. Я просто предпочитаю его иметь, чем не иметь. И как разработчик проекта, и как новичок на новом месте.