Как делают документацию?

Иди в универ.

2anonymous: ты явно не догоняешь смысл вопроса

я тоже хочу прочитать ответ на этот вопрос, уж сильно он болезненный.

наверное, она создаётся сразу же в процессе разработки... по-любому им надо как-то объяснять техникам/сборщикам что делать. А потом писатели её вылизывают и убирают те части которые другим видеть не надо =)

Девелоперы и пишут. Потом отдают работягам, чтобы те им по документации опытных образцов делали. Кривая документация будет - работяги её отпнут на доработку, и это правильно. Это только в быдлоконторах сперва натворят а потом сидят репу чешут, документируют чё получилось.

Точно...

Предлагаю взглянуть на Javadoc или Oxygen

>Предлагаю взглянуть на Javadoc или Oxygen

Javadoc, doxygen, phpDocumenter позволяют делать только документацию по API (если в исходнике написать пространную статью о внутреннем устройстве, она тоже попадёт). Вот так и делают. А ещё есть такая книга "Анализ программного кода на примере OpenSource", там приведены примеры удачной документации (немного).

>Девелоперы и пишут.

Ну далеко не всегда девелопер сможет написать нормальную документацию:). У нас в конторе этим занимается отдел QA.

>Это только в быдлоконторах сперва натворят а потом сидят репу чешут, документируют чё получилось.

Согласен на все 100%. Оффтоп: когда-то читал в ЖЖ заметки одного из работников Майкрософт, русского по происхождению. Так вот, когда Еврокомиссия потребовала от корпорации предоставить всю внутреннюю документацию по какой-то версии Винды, то пришлось в срочном порядке эту доку писать, потому как ее просто не было:).

> Ну далеко не всегда девелопер сможет написать нормальную документацию:). У нас в конторе этим занимается отдел QA.

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

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

Бугога! Впрочем, можно догадаться о таком положении дел по конечному "протухту".

> которое потом скармливает быдлокодерам для воплощения в коде.

где ты встречал такую организацию работы?

> Начавший с кодинга а не с разработки обречён затратить всемеро больше усилий на глюколовку и кучю последующих "рефакторингов"

это понятно, но АПИ таки зависит от имплементации. И искусство проектировщика сделать АПИ _выглядящим_ так как будто оно не зависит от имплентации.

> где ты встречал такую организацию работы?

в некоторых местах

> АПИ таки зависит от имплементации. И искусство проектировщика сделать АПИ _выглядящим_ так как будто оно не зависит от имплентации.

Смысл этой фразы ускользнул от меня.

> в некоторых местах

в cboss наверно

Расскажу, как делаю я.

Пишу код. В Специальных комментах размещаю описание функций. В начале каждого файла описываю назначение определяемых функций. Потом, с помощью перла, распарсиваю это дело, делаю документацию, и попутно строю граф вызовов функций в формате graphviz (после чего перегоняю его в ps, распечатываю и вешаю на стену :)) Документация и граф - весьма сильно помогают. Графы так же приходится строить при изучении исходников, написанных не мною.