Как научиться вести документацию?

← →
TUser © (2013-02-03 00:12) [0]

Посоветуйте руководства по ведению технической документации к проектам (developer guide). Сейчас я, конечно, что-то записываю, но нутром чувствую, что бардак. Другой человек точно не разберется, да и сам через несколько лет боюсь ничего не понять.

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

Что посоветует народ? Автодок? UML? Иное?

← →
Игорь Шевченко © (2013-02-03 00:39) [1]

Народ посоветует технического писателя

← →
Германн © (2013-02-03 01:42) [2]

> TUser © (03.02.13 00:12)
>
> Посоветуйте руководства по ведению технической документации
> к проектам (developer guide).

А что ты под этим подразумеваешь? Для кого и для чего нужна та документация, про которую ты говоришь?

← →
KilkennyCat © (2013-02-03 02:43) [3]

ну я просто плюнул на это дело. пишу, как получится, когда получится и где.
тут нужна особенная психология, ибо, например, у меня при начале проекта мысли: боже, как сложно, надо все описать. а при окончании: какая простая и понятная фигня, че-тут описывать?!

← →
TUser © (2013-02-03 10:15) [4]

> Для кого и для чего нужна та документация, про которую ты
> говоришь?

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

← →
Kerk © (2013-02-03 13:12) [5]

> TUser © (03.02.13 10:15) [4]

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

← →
Andy BitOff © (2013-02-03 13:36) [6]

TUser © (03.02.13 00:12)

http://www.devjetsoftware.com/products/documentation-insight/
В Dxe2 встроен огрызок, но, имхо, лучше купить.

← →
DVM © (2013-02-03 14:03) [7]

> Kerk © (03.02.13 13:12) [5]

> Самая надежная документации автоматически генерируется по
> коду.

Документацию в коде тоже надо постоянно в актуальном состоянии поддерживать. Это несколько легче, чем отдельно, но тоже будет съедать солидную часть времени разработки. Имхо актуально только для библиотек.

← →
DVM © (2013-02-03 14:26) [8]

> Andy BitOff © (03.02.13 13:36) [6]

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

← →
Kerk © (2013-02-03 16:45) [9]

> DVM © (03.02.13 14:03) [7]
>
> > Kerk © (03.02.13 13:12) [5]
>
> > Самая надежная документации автоматически генерируется по
> > коду.
>
> Документацию в коде тоже надо постоянно в актуальном состоянии
> поддерживать.

А я не говорил о документации в коде, я говорил о самом коде.

← →
DVM © (2013-02-03 17:03) [10]

> Kerk © (03.02.13 16:45) [9]

Тогда как понять:

> Самая надежная документации автоматически генерируется по
> коду.

Не один генератор не объяснит назначения метода, ну нагенерит он пустышек с указанием (даже не описанием) типов входных и выходных параметров и что с того толку?

← →
Kerk © (2013-02-03 17:55) [11]

> DVM © (03.02.13 17:03) [10]

Имя метода, имена параметров, имена типов, к какому модулю/классу метод принадлежит, ссылки на описание используемых типов, иерархии наследования. При нормальном подходе к разработке получится вполне вменяемое описание системы. Далекое, конечно, от идеала, зато его не нужно поддерживать вручную, оно достается бесплатно.

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

ИМХО.

← →
RDen © (2013-02-03 18:03) [12]

нет универсального решения

← →
Empleado © (2013-02-08 13:46) [13]

> Andy BitOff © (03.02.13 13:36) [6]
> TUser © (03.02.13 00:12)
>
> http://www.devjetsoftware.com/products/documentation-insight/
> В Dxe2 встроен огрызок, но, имхо, лучше купить.

Поддерживаю руками и ногами.
Версия Documentation Insight 2 Enterprise.
Экономит тучу времени, супер легок и удобен в использовании.

← →
SAPRO-NHK-SBOR (2013-02-08 19:03) [14]

на продажу или для себя?

← →
Rouse_ © (2013-02-08 19:06) [15]

> Andy BitOff © (03.02.13 13:36) [6]
> TUser © (03.02.13 00:12)
>
> http://www.devjetsoftware.com/products/documentation-insight/

Блин, понравилось, да и цена 250 евро, копейки.
Сеньк за линк.
А вопрос, вот в 2010-ом все эти расширенные хелпы (через тройной слэш) ниразу не работают (в подсказке к методу не отображаются), если навесить этот продукт, подсказки начнут нормально отображаться?

← →
DVM © (2013-02-09 12:00) [16]

> Rouse_ © (08.02.13 19:06) [15]

> А вопрос, вот в 2010-ом все эти расширенные хелпы (через
> тройной слэш) ниразу не работают (в подсказке к методу не
> отображаются), если навесить этот продукт, подсказки начнут
> нормально отображаться?

Там есть полнофункциональная триальная версия, можно проверить.

← →
Rouse_ © (2013-02-09 12:13) [17]

> DVM © (09.02.13 12:00) [16]

Блин, действительно, щас на семерке проверю...

← →
Rouse_ © (2013-02-09 12:19) [18]

Подсказку не заменяет, печально, только на уровне "DocumentationExplorer"& ну по крайней мере в Delphi 7

← →
Rouse_ © (2013-02-09 12:22) [19]

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

← →
DVM © (2013-02-09 12:26) [20]

> Rouse_ © (09.02.13 12:22) [19]

> Но вообще по логике должна быть оч удобная штука.

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

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

> Еще загромождает интерфейсную часть класса неслабо.

Да эт фигня, регион свернул и всего делов, мы щас как раз в регионах описание пишем, но неудобно что нет быстрого поиска, а тут все интегрируется в общую систему.

> Rouse_ © (09.02.13 12:31) [21]

> Да эт фигня, регион свернул и всего делов

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

> эта тулза вроде регионов по умолчанию не создает

у меня создало в семерке (свернуть правда нельзя)

Неа, удалять нужно. Ну или в настройках покопаться, чтоб не вставлял...

> Неа, удалять нужно.

или писать {$IFDEF версия делфи}{$REGION ...}...
Не знаю будет ли сворачиваться, но еще более громоздко

Ну мне это не важно, мы на 2010-ой сидим + у меня стоит купленная ХЕ3 (единственная на весь отдел) под 64-битные расширения оболочки.
Семерка только дома, я на ней код для статей ваяю :)

> Rouse_ © (09.02.13 12:55) [27]

> Семерка только дома, я на ней код для статей ваяю :)

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

> Eraser © (09.02.13 16:34) [28]

Лех, чур тебя наоборот я стараюсь писать код, проверяя чтоб он был рабочий от семерки до XE3 (правда только новый, старый лень править).

А с учетом что под семерку пишет очень много людей (судя по фидбэкам с моего сайта и блога) она очень еще актуальная.

Как научиться вести документацию? Найти похожие ветки