Ogre's Lab

Warning: count(): Parameter must be an array or an object that implements Countable in /home/bolyarco/www-ikratko/ogrelab/wp-content/plugins/microkids-related-posts/microkids-related-posts.php on line 645

Смята се за съвсем нормално, след като бъде приключен даден сайт (разработка и deployment) на юзерите да бъде даден един кирлив DOC файл с няколко screenshot-а, където е описано криво-ляво как се работи с този сайт или поне с админ панела му.

Всъщност -- въобще не е нормално -- даже и това не се прави. Обикновено някой от разработчиците отива на място в офиса на клиента и обяснява на някой служител или на групичка от служители как се работи. Цъка бързо насам-натам, това тук е за това, онова там за еди какво си, някакви въпроси има ли? Няма? Ами аз ще тръгвам тогава.

Представете си какво могат да разберат и запомнят юзерите от едно такова обучение… Най-вероятно -- почти нищо. После им се сърдим, че били тъпи, разсеяни и т.н.

Та думата тук ми се за писането на документация.

Имаше едно време един шеговит(в кавички може би) файл в който се говореше за истинският програмист. "Истинският програмист не пише документация" се казваше там…

Сега, на всички ни е ясно, че горното е пълна простотия и едва ли има място за подобни изцепки при професионална работа.

Докато потребителската документация едва ли трябва да се пише от програмистите (по-скоро не трябва), то за development документацията определено това трябва да е задължение основно на хората, които са направили архитектурата, детайлния дизайн и са надрали кода (обикновено е наличен само третия етап). Всеки път, когато ми се е налагало да доразвивам или променям някаква стара система, наличието на каквато и да било стара (но адекватна) документация ми е било от голяма полза.

Покрай писането на документацията за моя Tangra PHP5 Framework ми се наложи да се запозная с няколко инструмента/способа за писане/генериране на документация, които ми се струват доста полезни и искам да споделя някои впечатления:

1. PHPDocumentator (известен още като phpdoc)

Концепцията му е взаимствана от javadoc. Идеята е, че в source code-а се използват специално форматирани коментари, които съдържат описание и някои ключови (за phpdoc) думи и после от сорсовете директно се генерира документация като се използват тези коментари. Изходният формат е HTML , HTML/CHM, PDF или DocBook XML. HTML версиите позволяват промяна на вида чрез CSS.

PHPDocumentator е идеален за създаване на API reference. Слагайки подробни коментари в кода се постигат следните ефекти:

• кода става по-разбираем за други хора или дори за самите вас след време ако примерно няколко месеца не сте се занимавали с него и сте го забравили; Проблемът с раздуването на сорс файловете с прекалено много коментари се решава от съвременните IDE-a, като например Zend Studio, които позволяват коментарите да се колапсират;

• документацията е най-близо до кода и по този начин се намалява вероятността двете да излязат от синхрон;

• генерирането на API reference става по-лесно, отколкото по стария начин да се обиколят на ръка всички файлове и да се извадят всички класов и функции.

PHPDocumentator има и един съществен недостатък -- не става за създаване на Manual-и и Tutorial-и. Всъщност това би трябвало да е очевидно, но забелязвам, че има хора, които се опитват да го ползват и за това, подлъгвайки се от леснотата на създаване на API reference.

2. Docbook

Ако се занимавате с PHP най-вероятно почти всичката документация, която сте чели досега е била създадена чрез Docbook -- включително и PHP Manual-а е написан с Docbook.

Docbook най-накратко (и неточно) е XML, който след това може да се трансформира в различни изходни формати като PDF, HTML и т.н.

Всъщност Docbook е набор от правила за композиране на XML, като тези правила са дефинирани в няколко алтернативни езика като например SGML, XML DTDs и W3C XML Schema

Пример за docbook:

<book>
<title>Най-проста книга</title>
<preface><title>Въведение</title>
<para>
Здравейте, това е въведение.
</para>
</preface>
<chapter>
<title>Първа глава</title>
<para>Малко текст…</para>
</chapter>
</book>

Предимства на docbook:

• зряла и доказана технология;
• относително лесна за научаване;
• де факто стандарт за документация на FOSS проекти.

Недостатъци:

• изисква известно търпение в началото докато човек се ориентира кое как се ползва;
• не става за API reference, но за това си има PHPDocumentator.

В заключение

Има една поговорка:
"Майсторът се познава по инструментите"
Грехота е при положение, че имаме на разположение подходящите инструменти като Docbook и PHPDocumentator да не ги ползваме, а да си продължаваме с мърлявите DOC/ODT файлове.

This entry was posted by Ognyan Bankov on 2007-04-23 at 07:01:06 and is filed under Web development. You can follow any responses to this entry through the RSS 2.0 feed. Responses are currently closed, but you can trackback from your own site.