Языки разметки
Мы рекомендуем рассмотреть некоторые из современных схем описания документации для крупномасштабных проектов по документированию.
Многие авторы, пишущие на технические темы, используют в настоящее время средство DocBook для описания своих документов. DocBook представляет собой стандарт описания документов на основе SGML, который тщательно идентифицирует каждый компонент в документе. Документ можно обрабатывать процессором DSSSL для его преобразования в любое число различных форматов. Проект документации Linux использует DocBook для представления информации в форматах RTF, ТеХ, info, PostScript и HTML.
Пока ваше первоначальное описание достаточно насыщено, чтобы выразить все необходимые концепции (включая гиперссылки), перевод публикации в любую другой форму не составит труда и будет выполняться автоматически. Вы можете создавать интерактивную справку, руководства, описание основных свойств продукта для помещения на web-сайт и даже календарь с ежедневными советами – все из одного и того же источника, который находится в системе управления исходным текстом и собирается в ходе процедуры ночной сборки основной программы (см. "Вездесущая автоматизация").
Документация и программа – это различные визуальные представления одной и той же основополагающей модели, но лишь визуальные представления имеют право разниться. Не позволяйте документации превращаться в гражданина второго сорта, которому запрещено участвовать в основном документообороте проекта. Обращайтесь с документацией так же бережно, как вы обращаетесь с программой, и пользователи (а также сотрудники службы сопровождения) будут петь вам осанну.
Другие разделы, относящиеся к данной теме:
• Пороки дублирования
• Ортогональность
• Преимущества простого текста
• Управление исходным текстом
• Всего лишь визуальное представление
• Программирование в расчете на стечение обстоятельств
• Карьер для добычи требований
• Вездесущая автоматизация
Вопросы для обсуждения
• Приходилось ли вам писать пояснительный комментарий для исходного текста программы, который вы только записали? Почему нет? Не было времени? Не уверены, что программа действительно работает – пробуете некую идею в виде прототипа? Впоследствии вы выбросите эту программу, не правда ли? Ведь при этом она не попадет в проект без комментариев и в экспериментальном виде, не так ли?
• Иногда неудобно документировать проектное решение исходного текста программы, поскольку это решение вам не совсем ясно – оно еще на стадии развития. Вы полагаете, что не должны тратить свои усилия впустую, описывая, как работает что-то, еще до того, как оно действительно начинает работать. Не похоже ли это на программирование в расчете на стечение обстоятельств? (См. одноименный раздел.)