К сожалению, в настоящее время все больше проектной документации составляется с помощью текстовых процессоров, сохраняющих файл на диске в некоем определенном формате. Мы говорим «к сожалению», потому что это существенно ограничивает возможности автоматической обработки документа. Но у вас в запасе имеется еще два варианта:
• Создавайте макрокоманды. Сейчас большинство многофункциональных текстовых процессоров содержит встроенные макроязыки. Затратив некоторое усилие, вы можете запрограммировать их таким образом, чтобы экспортировать отмеченные разделы документов в альтернативные формы, которые вам необходимы. Если программирование на таком уровне является для вас болезненной процедурой, вы всегда можете экспортировать соответствующий раздел в файл, имеющий стандартный формат простого текста, а затем воспользоваться инструментальным средством наподобие Perl для преобразования его в окончательную форму.
• Сделайте документ подчиненным. Вместо того, чтобы использовать документ в качестве определяющего источника, возьмите другое представление. В примере с базой данных вы хотели бы использовать схему в качестве авторитетной информации. Тогда создайте средство, которое экспортирует эту информацию в ту форму, которую документ может импортировать. Однако при этом будьте внимательны. Вы должны быть уверены, что эта информация импортируется всякий раз, когда документ выводится на печать, а не единожды, при создании этого документа.
Аналогичным образом можно генерировать документацию на уровне API из исходного текста программы, пользуясь инструментальными средствами, такими как JavaDoc и DOC++. Моделью является исходный текст программы: компилироваться может одно визуальное представление модели; другие представления предназначены для вывода на печать или просмотра на web-странице. Наша цель – работа над моделью (неважно, является ли эта модель самой программой или же каким-либо иным документом), и мы должны добиться того, чтобы все эти представления обновлялись автоматически (см. «Вездесущая автоматизация»).
Внезапно документация оказывается не столь уж плохой.
Технические писатели
До этого момента мы говорили лишь о внутренней документации, той которую составляют сами программисты. Но что происходит, если в вашем проекте участвуют профессиональные технические писатели? Слишком часто программисты просто «перекидывают» материал техническим писателям и дают им возможность заработать себе на жизнь, создавая руководства пользователей, рекламные материалы и т. д.
Это является ошибкой. То, что программисты не составляют такие документы, вовсе не означает, что мы можем поступиться прагматическими принципами. Мы хотим, чтобы писатели восприняли те же основные принципы, что и прагматики, – соблюдали принципы DRY, ортогональности, а также концепцию «модель-визуальное представление», применяли автоматизацию и сценарии.
Печатать документ или ткать его на холсте?
Издаваемой бумажной документации присуща одна проблема: она может устареть, пока будет напечатана. Документация в любой ее форме – лишь моментальный снимок.
Поэтому мы стараемся создавать всю документацию в форме, которая может быть помещена в информационную сеть, на web-страницу вместе с гиперссылками. Такое представление документации легче сохранять в обновленном виде, чем отслеживать все существующие бумажные экземпляры, уничтожать их и распространять обновленные версии. Это также является лучшим способом обращения к нуждам широкой аудитории. Однако не забывайте помещать дату или номер версии на каждой web-странице. В этом случае читатель сможет разобраться, что соответствует текущему моменту, что изменилось недавно, а что осталось неизменным.
Во многих случаях вам приходится представлять одну и ту же документацию в различных форматах: в печатном, в виде web-страницы, экранной справки, а может быть, и как слайд-шоу. Обычное решение в большой степени полагается на технологию «вырезать и вставить» на и создание нескольких независимых документов из одного оригинала. Это неудачная идея: представление документа не должно зависеть от его содержания.
Если вы пользуетесь системой описания документов, то обладаете гибкостью, чтобы реализовать столько различных выходных форматов, сколько вам нужно. Вы можете использовать