Ох уж это документирование...

Самая нудная и самая неинтересная часть моей работы - разработка документации. Захотелось поделиться / поплакаться.
Все сказанное касается прежде всего разработчиков каких-либо программ. Особенно программ, которые будут отдаваться кому-то там на сторону и функционировать отдельно от разработчика.

Предположим, что программа написана, оттестирована в самых неожиданных сочетаниях (что уже практически нереально, но - допустим!), и вообще код готов к тому, чтобы быть установленным "куда-то там налево" :) Даже инсталлятор написан (хотя это и редкость, особенно если вопрос касается lisp-разработок)

Осталась сущая мелочь - написать документацию.

Да, я знаю про самодокументирующийся код. Да, я видел решения Андрея Бушмана. Но тем не менее...

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

Что должна в себе содержать документация "для пользователя"? По идее джентельменский набор таков: последовательность установки, переустановки, удаления программы, как вернуть настройки в "базовые" (если, конечно, вообще настройки есть), какие особые требования программа предъявляет к железу и ПО (например, права доступа на определенные каталоги; права доступа в некоторые ветки реестра; ограничения на работу с сетевыми ресурсами и т.п.). Ну и, естественно, "как работать с программой".

Документация для программиста должна содержать в себе уже другую информацию: какие значения в реестр и какой процедурой записываются; какие конфигурационные файлы и за что отвечают; как править конфигурационные файлы; чем и как можно расширить/изменить функиционал программы.

На самом деле есть еще и третий документ, который обязательно надо сделать. Это документ, описывающий последовательность установки / переустановки / удаления программы. Ну и требования к квалификации пользователя, как же без них: если пользователь не умеет компьютер толком выключить, то о чем можно говорить? :)

И напоследок небольшая памятка: если в программе (или наборе программ, не суть важно) изменилось хоть что-то, хоть чуть-чуть добавился или удалился функционал,- сразу же, моментально(!) надо вносить изменения в документацию. Оставлять эту задачу "на потом" означает только одно - не сделать ее никогда.

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