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