Подскажите средство создания и ведения документации, для Delphi

← →
Dust © (2006-10-12 15:45) [0]

см Subj.
Хочу задокументировать свою библиотеку классов. Более того пришёл к необходимости вести документацию непосредственно во время написания проекта.

← →
Jeer © (2006-10-12 15:49) [1]

1. бумага + карандаш
2. notepad

← →
Dust © (2006-10-12 15:55) [2]

!up
2 Jeer: Исходные коды тоже можно в блокноте писать, а не в IDE, и диаграммы ручками рисовать а не в Visio

← →
Jeer © (2006-10-12 16:06) [3]

> Исходные коды тоже можно в блокноте писать, а не в IDE,
> и диаграммы ручками рисовать а не в Visio

Пиши.

А по сабжу - глупости все это, т.к. лучше исходного кода, да еще своего нет ничего.

← →
Dust © (2006-10-12 16:14) [4]

Ничего подобного.
Я уже через неделю забываю подробности проекта, основных идей заложенных в базовых классах, тонкости поведения при вызове методов,...
А потом - постороннему человеку, особенно через некоторое время очень тяжело объяснить почему здесь потребовалось сделать 4 уровня абстракции, а не 2, или не один, даже несмотря на то что при проектировании, или кодировании на это были серьёзные причины.
Короче исходники исходниками, а документация всёравно нужна.

← →
Kolan © (2006-10-12 16:18) [5]

UML итд....

← →
Jeer © (2006-10-12 16:20) [6]

> Я уже через неделю забываю подробности проекта,

Тогда стоит другим делом заняться.

А документацию никто и не отменял - см [1]
Это минимум:)

← →
Dust © (2006-10-12 16:32) [7]

2 Jeer

> Тогда стоит другим делом заняться.

Улицы подметать? Хамство не красит человека...

> Это минимум

Минимума мне мало.

← →
Jeer © (2006-10-12 16:42) [8]

Dust © (12.10.06 16:32) [7]

> Улицы подметать?

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

← →
Dust © (2006-10-12 16:46) [9]

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

← →
Ketmar © (2006-10-12 16:56) [10]

doxygen?

← →
Ш-К (2006-10-12 16:57) [11]

Если диаграмма классов сложна для понимания, могу предложить поставлять с ней диаграмму объектов, что инстанцируются этими классами. Желательно не одну.
Хотя, при правильной разработке и использовании корпаративных стандартов и паттернов такой проблемы не возникнет.

← →
Dust © (2006-10-12 16:58) [12]

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

← →
Jeer © (2006-10-12 17:11) [13]

> Dust © (12.10.06 16:46) [9]

> судя по всему

- верно, давно уже лечу нуждающихся в этом.

> Меня смутил мастер,

Не удивительно, на то он и мастер:)

WithClass 2000
ModelMaker
Rational Rose
...
etc

Пробуй:)

← →
Dust © (2006-10-12 17:29) [14]

Удалено модератором
Примечание: Создание пустых сообщений

← →
Dust © (2006-10-12 17:50) [15]

ОК
Я переформулирую вопрос. Как ВЫ документируете собственные наработки?
Как и чем сделать в конечном итоге chm - файл?

← →
Jeer © (2006-10-12 18:10) [16]

1. самодокументированность кода;
2. комментарии;
3. техническая документация, если нужна;
4. ErWin для datebase;

chm - это особая ("компилированная") форма содержимого web-каталога.
htm2chm от http://yarix.by.ru/

← →
Jeer © (2006-10-12 18:11) [17]

P.S.
Если очень хочется - поэксперементируй с набором экспертов GExperts.
Free & sourse

← →
Ketmar © (2006-10-12 18:26) [18]

>[15] Dust(c) 12-Oct-2006, 17:50
>Я переформулирую вопрос. Как ВЫ документируете собственные
>наработки?
а никак. комментариями в коде, в основном. которые потом достаются простым препроцессором. %-)

а chm не делаю ни за какие коврижки -- я не самоубийца. plain html -- это наше всё. %-)

← →
Dust © (2006-10-12 18:31) [19]

Хорошая тулза.... исключительно хорошая, но как-то её маловато

← →
Dust © (2006-10-12 18:34) [20]

2 Ketmar: поясни
> ..я не самоубийца..

достаются простым препроцессором

чем-чем они достаются? каким именно препроцессором? самописным?

http://pasdoc.sipsolutions.net/ ?

>[20] Dust(c) 12-Oct-2006, 18:34
>2 Ketmar: поясни
>> ..я не самоубийца..
chm must die. as a matter of taste. %-)

>чем-чем они достаются? каким именно препроцессором?
>самописным?
натурально, самописным. люблю велосипеды делать. %-)

> с ней диаграмму объектов, что инстанцируются этими классами

ээ кажется это классы инстанцируют... Те создают их экземпляры.

> Dust

А UML почему не подошел?

> Dust © (12.10.06 17:50) [15]
> ОК
> Я переформулирую вопрос. Как ВЫ документируете собственные
> наработки?
> Как и чем сделать в конечном итоге chm - файл?

1. я в самодукоментруемость кода не верю - в сложный проектах с нетривиальной логикой это проблематично - все равно, как ни старайся общая идея проекта должна быть где-то изложена. Т.е. имхо нужен текст. UML может только подкрепить доку.
2. я документирую не проект, а процесс разработки. есть собственная утилита, собирающая из word файлов chm: сначала doc переводится в html, потом собирается с помощью htmlworkshop.
3. я пишу две ветки в документации:
а) список релизов. релизы нумеруются в виде Y.MajorRelease.MinorRelease. Где Y - год разраобтки, MajorRelease - номер, в рамках которого делается ощутимая часть работы. При начале любой работы делается inc для MajorRelease, если прошлый релиз был выкачен в общее пользование. MinorRelease - номер внутри MajorRelese. Обычно каждый билд, предназанченный для внутреннего пользования (тестирование, например), сопровождается новым MinorRelese"ом.
б) задачи. В каздой задаче указано, в кажом релизе она была выполнена.
4. Для связи кода с докой используется следующий подход.
а) из доки ссылки в код делаются по имени модулей, классов и пр. Т.е. ничего оригинального.
б) код ссылается на доку следующим образом:
* Каждый документ в доке имеет уникальный номер, который приваивает автор доки.
* Есть свой протокол tech-doc, который обрабавается собственной программой. Т.е. набираешь где угодно, хоть в браузере, хоть в total commander tech-doc://myproject?id=123123 и будет открыт chm на нужной странице.
* Есть собственное расширение для IDE, которое при нажатии определенного сочетанания клавиш (у меня ctrl+shift+b) берет выделенный тект и переходит по нему. Поэтому я иногда в комментария пишу:
// Это сделано согласно задаче tech-doc://project1?id=2323.
Выделяешь tech-doc://project1?id=2323, нажимаешь ctrl+shift+b и получаешь текст описания.
5. Еще бы хотел добавить про uml. Имхо он не самодостаточен для людей, НЕ являющихся в очень хорошими профи в UML. Во-первых, он меняется со временем. Вводятся новые стандарты. В полследней версии много нового. Во-вторых, найти в рускоязычной литературе *строгое* описание нотации имхо невозможно. Обычно это декларативное описание разных частей UML. Но строго описания я не видел. В такой ситуации сложно ожидать от команды однозначного и хорошего понимания UML.
UML можно использовать для разработки. Но не так, на бумаге, а с помощью определенной среды (rational, напр.). Среды обычно диктуют свою страктовку UML. Волей не волей будешь тактовке следовать. В итоге все будут однозначно понимать ее.
Хотел бы акцентировать внимание на том, что я считаю UML крайне полезной штукой, но для ее успешного использования нужно приложить очень немало сил.
Другой вопрос, что UML имеет массу хороших частей, который могут быть использованы вне рамок полноценного процесса разработки с использование UML. Напр. диаграммы классов и диаграммы последовательностей. Диаграммы пакетов (так, кажется) тоже полезны, для обозначения зависимостей.
Мой резьюм такой - надо писать обычный человеческий текст, сопровождаемый рисунками из UML, которые по своей простоте просто не могут быть неоднозначно истолкованы. Напр, те же диаграммы классов.

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

Документировать же проект, достаточно сложно - трудоновато отслеживать изменения.

PasDoc хорошая вещь, мне нравилась. Делает и HTML и CHM.

2 Суслик
Серьёзный подход.. Особенно с разработкой своего протокола tech-doc и собственного ПО для документирования... Даже не знаю, подсилу ли мне разрабатывать всё это только для документирования собственных проектов.

> Документировать же проект, достаточно сложно - трудоновато
> отслеживать изменения.

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

> Особенно с разработкой своего протокола tech-doc и собственного
> ПО для документирования... Даже не знаю, подсилу ли мне
> разрабатывать всё это только для документирования собственных
> проектов.

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

Файл "TECH-DOC Key.reg"

Windows Registry Editor Version 5.00 [HKEY_CLASSES_ROOT\TECH-DOC] @="URL:Протокол TECH-DOC" "URL Protocol"="" [HKEY_CLASSES_ROOT\TECH-DOC\shell] [HKEY_CLASSES_ROOT\TECH-DOC\shell\open] [HKEY_CLASSES_ROOT\TECH-DOC\shell\open\command] @="\"E:\\TDA\\Work\\ProjectsOutput\\2006\\TechDocProtocolPlugin.exe\" %1"

TechDocProtocolPlugin.exe просто в командной строке получает урлу - далее обработка 10 строк (распарсить и вызывать shellexecute)

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

> Документировать после написания проекта вообще глупо. Абсолютно
> согласен с тем, что нужно документировать процесс разработки

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

Я имел ввиду начинать документировать уже по готовому.

Подскажите средство создания и ведения документации, для Delphi Найти похожие ветки