За писането на документация за Web сайтове/приложения

Posted / Публикувана 2007-04-23 in category / в категория: Web development

Смята се за съвсем нормално, след като бъде приключен даден сайт (разработка и 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 файлове.

One Response to “За писането на документация за Web сайтове/приложения”

  1. Ogre's blog » За писането на документация за Web сайтове/приложения Says:

    […] Тази публикация беше преместена на ново място: За писането на документация за Web сайтове/приложения […]