Шрифт:
Это является ошибкой. То, что программисты не составляют такие документы, вовсе не означает, что мы можем поступиться прагматическими принципами. Мы хотим, чтобы писатели восприняли те же основные принципы, что и прагматики, – соблюдали принципы DRY, ортогональности, а также концепцию "модель-визуальное представление", применяли автоматизацию и сценарии.
Печатать документ или ткать его на холсте?
Издаваемой бумажной документации присуща одна проблема: она может устареть, пока будет напечатана. Документация в любой ее форме – лишь моментальный снимок.
Поэтому мы стараемся создавать всю документацию в форме, которая может быть помещена в информационную сеть, на web-страницу вместе с гиперссылками. Такое представление документации легче сохранять в обновленном виде, чем отслеживать все существующие бумажные экземпляры, уничтожать их и распространять обновленные версии. Это также является лучшим способом обращения к нуждам широкой аудитории. Однако не забывайте помещать дату или номер версии на каждой web-странице. В этом случае читатель сможет разобраться, что соответствует текущему моменту, что изменилось недавно, а что осталось неизменным.
Во многих случаях вам приходится представлять одну и ту же документацию в различных форматах: в печатном, в виде web-страницы, экранной справки, а может быть, и как слайд-шоу. Обычное решение в большой степени полагается на технологию "вырезать и вставить" на и создание нескольких независимых документов из одного оригинала. Это неудачная идея: представление документа не должно зависеть от его содержания.
Если вы пользуетесь системой описания документов, то обладаете гибкостью, чтобы реализовать столько различных выходных форматов, сколько вам нужно. Вы можете использовать
<H1>Chapter Title</Н1>
для генерации новой главы в отчетной версии документа и названия нового слайда в слайд-шоу. Можно воспользоваться технологиями типа XSL и CSS [54] для генерирования множественных выходных форматов из этого описания.
Если вы используете текстовый процессор, то, по всей вероятности, будете располагать аналогичными возможностями. Если не забывали использовать стили для идентификации различных элементов документа, то, применяя различные таблицы стилей, вы можете существенным образом изменить внешний вид окончательного результата. Большинство современных текстовых процессоров позволяет конвертировать документы в форматы типа HTML для публикации на web-сайтах.
54
Технологии XSL и CSS были разработаны для отделения представления от содержимого.
Языки разметки
Мы рекомендуем рассмотреть некоторые из современных схем описания документации для крупномасштабных проектов по документированию.
Многие авторы, пишущие на технические темы, используют в настоящее время средство DocBook для описания своих документов. DocBook представляет собой стандарт описания документов на основе SGML, который тщательно идентифицирует каждый компонент в документе. Документ можно обрабатывать процессором DSSSL для его преобразования в любое число различных форматов. Проект документации Linux использует DocBook для представления информации в форматах RTF, ТеХ, info, PostScript и HTML.
Пока ваше первоначальное описание достаточно насыщено, чтобы выразить все необходимые концепции (включая гиперссылки), перевод публикации в любую другой форму не составит труда и будет выполняться автоматически. Вы можете создавать интерактивную справку, руководства, описание основных свойств продукта для помещения на web-сайт и даже календарь с ежедневными советами – все из одного и того же источника, который находится в системе управления исходным текстом и собирается в ходе процедуры ночной сборки основной программы (см. "Вездесущая автоматизация").
Документация и программа – это различные визуальные представления одной и той же основополагающей модели, но лишь визуальные представления имеют право разниться. Не позволяйте документации превращаться в гражданина второго сорта, которому запрещено участвовать в основном документообороте проекта. Обращайтесь с документацией так же бережно, как вы обращаетесь с программой, и пользователи (а также сотрудники службы сопровождения) будут петь вам осанну.
• Пороки дублирования
• Ортогональность
• Преимущества простого текста
• Управление исходным текстом
• Всего лишь визуальное представление
• Программирование в расчете на стечение обстоятельств
• Карьер для добычи требований
• Вездесущая автоматизация
• Приходилось ли вам писать пояснительный комментарий для исходного текста программы, который вы только записали? Почему нет? Не было времени? Не уверены, что программа действительно работает – пробуете некую идею в виде прототипа? Впоследствии вы выбросите эту программу, не правда ли? Ведь при этом она не попадет в проект без комментариев и в экспериментальном виде, не так ли?