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