Стандарты на техническую документацию

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

1. Стандарты на процесс создания документации. Определяют способ создания технической документации.

2. Стандарты на документ. Определяют структуру и внешний вид документов.

3. Стандарты на обмен документами. Гарантируют совместимость всех электронных версий документов.

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

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

Рис. 24.3. Процесс создания документации, включающий проверку качества документов

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

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

Приведем примеры различных стандартов на документацию.

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

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

3. Стандарты внешнего вида документации. Эти стандарты определяют “фирменный” стиль документов: использование шрифтов и стилей, логотипов, названия фирмы, цветовых выделений для элементов структуры документа и т.д.

4. Стандарты на обновление документации. Так как документы должны отображать изменения, возникающие в процессе разработки системы, желательно применять последовательный способ обозначения изменений в документации. Чтобы выделить новую, измененную версию документа, для печатных документов можно использовать обложки разных цветов, а для выделения изменений в тексте можно делать цветовые указатели на полях.

Особая роль отводится стандарту на совместимость документов, так как часто приходится работать с разными электронными версиями документов. Использование стандартов на совместимость позволяет осуществлять передачу документов в электронном виде и при необходимости восстанавливать их в первоначальном виде.

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