Эндрю Хант - Программист-прагматик. Путь от подмастерья к мастеру

Если документ хранится в виде простого текста вместе с командами описания документов (например, в виде HTML, LATeX. или troff), то в этом случае можно использовать такие инструментальные средства, как Perl, для извлечения схемы и ее автоматического переформатирования. Если документ хранится в двоичном формате текстового процессора, то ознакомьтесь с некоторыми вариантами действий, приведенных во врезке, данной ниже.

Теперь документ – неотъемлемая часть разработки проекта. Единственным способом изменения схемы является изменение документа. Вы гарантируете, что спецификация, схема и программа находятся в согласии. Вы сводите к минимум работу, которую необходимо выполнить для внесения каждого изменения, и можете обновлять визуальные представления изменений автоматически.

К сожалению, в настоящее время все больше проектной документации составляется с помощью текстовых процессоров, сохраняющих файл на диске в некоем определенном формате. Мы говорим «к сожалению», потому что это существенно ограничивает возможности автоматической обработки документа. Но у вас в запасе имеется еще два варианта:

• Создавайте макрокоманды.Сейчас большинство многофункциональных текстовых процессоров содержит встроенные макроязыки. Затратив некоторое усилие, вы можете запрограммировать их таким образом, чтобы экспортировать отмеченные разделы документов в альтернативные формы, которые вам необходимы. Если программирование на таком уровне является для вас болезненной процедурой, вы всегда можете экспортировать соответствующий раздел в файл, имеющий стандартный формат простого текста, а затем воспользоваться инструментальным средством наподобие Perl для преобразования его в окончательную форму.

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

Аналогичным образом можно генерировать документацию на уровне API из исходного текста программы, пользуясь инструментальными средствами, такими как JavaDoc и DOC++. Моделью является исходный текст программы: компилироваться может одно визуальное представление модели; другие представления предназначены для вывода на печать или просмотра на web-странице. Наша цель – работа над моделью (неважно, является ли эта модель самой программой или же каким-либо иным документом), и мы должны добиться того, чтобы все эти представления обновлялись автоматически (см. «Вездесущая автоматизация»).

Внезапно документация оказывается не столь уж плохой.

До этого момента мы говорили лишь о внутренней документации, той которую составляют сами программисты. Но что происходит, если в вашем проекте участвуют профессиональные технические писатели? Слишком часто программисты просто «перекидывают» материал техническим писателям и дают им возможность заработать себе на жизнь, создавая руководства пользователей, рекламные материалы и т. д.

Это является ошибкой. То, что программисты не составляют такие документы, вовсе не означает, что мы можем поступиться прагматическими принципами. Мы хотим, чтобы писатели восприняли те же основные принципы, что и прагматики, – соблюдали принципы DRY, ортогональности, а также концепцию «модель-визуальное представление», применяли автоматизацию и сценарии.

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

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