Если не установить правила оформления документации, редакторы, художники и т.п., подобно программистам, будут действовать в зависимости от своих вкусов и наклонностей. Чтобы продукция имела профессиональный вид, следует начать с подбора соответствующих стандартов.
Одним из важнейших стандартов является руководство по стилю. В нем устанавливаются виды документации и даются основные рекомендации по оформлению: размер страницы, шрифт, стиль художественного оформления, требования к словарю терминов, порядок индексирования, способ нумерации разделов и отыскания нужных сведений, формат печати и др. Выделяются следующие основные виды документации:
· Техническое описание системы. Это введение, излагающее основные концепции программного изделия. Оно дает будущему пользователю сведения о принципах функционирования и возможностях программного изделия, характеризует программное изделие в терминах наиболее общих его функций и освещает самые существенные свойства. Изложение должно быть четким и касаться наиболее важных характеристик системы. Это описание предназначено для лиц, которые могут быть не знакомы с программированием и принципами работы ЭВМ, но которые определяют выбор и приобретение средств вычислительной техники. Основным первоисточником для технического описания должно быть соглашение о требованиях, дополненное материалами групп разработки и поддержки.
· Справочное руководство. В нем подробно описаны все внешние характеристики программного изделия. Оно обеспечивает пользователю набор информации о назначении программного изделия, о необходимом оборудовании и его конфигурации, о языках программирования, включая форматы команд и сообщений, о структурах входных и выходных данных, о взаимосвязях с другими программными изделиями. При этом предполагается, что читатель справочного руководства имеет опыт работы с программами и техническими средствами ЭВМ. Справочное руководство составляется на основе внешних спецификаций. Дополнительный материал поставляет группа разработки. Это руководство предназначено для программистов и системных аналитиков, которые являются непосредственными пользователями программного изделия.
· Справочный буклет. Он обычно имеет карманный формат и содержит краткие сведения из справочного руководства. Он позволяет быстро ознакомиться с форматами операторов, мнемоникой операций, таблицами преобразования кодов, синтаксисом языка. В наиболее сжатой форме этот документ называют справочным формуляром.
· Руководство оператора содержит информацию для пользователей, которая указывает, как эксплуатировать программу и соответствующее оборудование. Оно описывает требуемые характеристики технических средств, управляющие сообщения и рабочие процедуры. В характеристиках оборудования излагаются сведения о минимально необходимой конфигурации, специальных возможностях оборудования и способах закрепления аппаратных ресурсов за программами. В описании управляющих сообщений даются их форматы и правила использования, а также конкретные примеры. В рабочих процедурах описываются все последовательные этапы управления системой, включая начальную загрузку, выполнение заданий и восстановление после отказов. Основным источником для написания руководства оператора служат внешние спецификации. Дополнительная информация поступает от группы разработки и группы испытаний. Руководство предназначено для операторов, которые могут и не иметь большого опыта работы.
· Указатель системных сообщений. В этом документе описываются все сообщения, порождаемые программой, а также ситуации, в которых они возникают, и необходимые действия оператора. Указатель составляется, в основном, по листингам программ и предназначен для операторов, программистов и системных аналитиков.
В интерактивном режиме появляется возможность оперативно выводить справочную информацию на экран. В таких системах выдается большое количество сообщений — подсказок и сообщений об ошибках. Группа разработки проектирует лишь программный механизм подобного взаимодействия, ответственность за окончательную реализацию текстов сообщений, их стиль и форматы несет группа выпуска документации. Она приводит и проверяет соответствие печатных материалов сообщениям, выдаваемым в режиме on-line.
Кроме соблюдения стиля документов, группа выпуска документации определят поток работ, начиная от планирования и кончая распространением программного изделия. В этой инструкции описываются методы, позволяющие планировать процесс выпуска документации и контролировать выполнение календарного плана.