6.7 Документация

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

Документация для пакета программ создается обычно по двум причинам. Прежде всего она объясняет свойства программного обеспечения и описывает, как его следует использовать. Такая документация называется пользовательской (user documentation). Поскольку она предназначена для чтения пользователем, она является нетехнической.

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

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

Другая цель создания документации — это описание внутреннего строения системы для обслуживания системы в будущем. Такая документация называется системной (system documentation), она по своей сути является более формальной, чем пользовательская документация. Главной составляющей системной документации являются исходные версии всех программ системы. Важно, чтобы эти программы были представлены в удобочитаемом формате, поэтому разработчики программного обеспечения поддерживают использование языков программирования высокого уровня, комментариев и модульного проектирования, которое позволяет представлять модули как отдельные единицы. Многие компании, создающие программное обеспечение, разработали правила, которых должны придерживаться их сотрудники при написании программ. Они включают в себя правила расположения текста программы на странице, правила наименования констант, переменных, объектов классов и правила написания документации. Эти правила помогают сделать программное обеспечение, создаваемое компанией, единообразным, что значительно облегчает процесс его обслуживания.

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

Это еще один довод в защиту CASE-инструментов. С их помощью гораздо легче перерисовывать диаграммы и обновлять словари данных, чем при использовании старых ручных методов. Следовательно, применение CASE-инструментов увеличивает вероятность того, что все необходимые обновления будут сделаны и документация будет точной.

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