Ведение проектной документации

У меня часто возникают утопические идеи по формализации разработки. Идеи о том, как удобно, технологично и современно организовать различные аспекты разработки. Эта статья посвящена работе с проектной документацией — ТЗ и РПЗ. Сразу оговорюсь, речь не идет о документации исходного кода — тут разумней всего применять PHPDoc и автоматические генераторы справки.

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

У меня есть 3 основных тезиса, касательно ведения проектной документации.

1. Документ должен быть представлен в исходном коде

Речь идет конечно не о программировании, я думаю любому ясно что оформление документа не является его частью. HTML тоже не уместен — он избыточен, не все им владеют, разметка иногда перегружает текст. Наиболее удачный вариант — WIKI-разметка, так как она лаконична, не портит сам текст, легка в освоении, структурна и удобна при просмотре в исходном виде. К ней необходимо добавить возможность просмотра «красивой» версии документа через веб-фронтэнд.

2. Документ должен храниться и управляться в SVN

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

3. Генерация в дружелюбный формат

Естественно, для отправки документации внешним относительно компании-разработчика контрагентам необходимо иметь возможность оформлять документ в одном из общепринятых форматов. Благодаря факторам выше мы имеем возможность генерировать однородное оформление документа на фирменном бланке компании. С автоматически формируемым оглавлением и историей изменений. Тут нужно упомянуть возможность отмечать некоторые ревизии как незначительные, чтобы исправление орфографических ошибок не засоряло журнал изменений. Лучше это делать с помощью особого свойства ревизии, ну или на крайний случай — пустого сообщения коммита (что конечно же очень не красиво и стоит этого избегать). Достоинства такого скрипта очевидны, даже если у компании поменяется фирменный стиль, переписав сам скрипт, а точнее шаблон, мы сможем быстро и без потерь перегенерировать всю документацию по текущим и даже архивным проектам.

Как быть с рисунками?

Да, это самый проблемный вопрос — и я не вижу идеального его решения, но вот несколько вариантов:
1. Включение в документ бинарных изображений. Проще всего и ближе к реальности. Тут минусы все те же, что при использовании бинарных форматов, нет diff и merge, но допустим для картинок это не очень то нужно. Второй минус при просмотре текста не видно картинки, стало быть теряется из вида часть информации. Можно решить специальными инструментами просмотра либо семантической политикой именования файла.
2. SVG. Недостатки те же что у HTML — нечитаемо из текста, да и набор инструментов ограничивается. К примеру, где в Visio экспорт в svg?
3. Псевдографика. А что нормальный вариант, как в RFC-шках. Monospace-шрифт и вперед. Очень ограничены возможности — более-менее серьезную блок-схему уже не нарисуешь.

Конечно, на практике лучше использовать комбинацию пунктов 1 и 3 в разумных пределах.