Документирование программных средств

Документация на программное обеспечение — это документы, сопровождающие некоторое программное обеспечение (ПО) — программу или программный продукт. Эти документы описывают то, как работает программа и/или то, как её использовать.

Документирование — это процесс создания документации, важная часть в разработке программного обеспечения, ей часто уделяется недостаточно внимания.

Цель документирования – создание средства передачи информации между разработчиками ПС, средства управления разработкой ПС и средства передачи пользователям информации, необходимой для применения и сопровождения ПС.

На создание этой документации приходится большая доля стоимости ПС.

Эту документацию можно разбить на две группы:

• Документы управления разработкой ПС.

• Документы, входящие в состав ПС.

Документы управления разработкой ПС (software process documentation) управляют и протоколируют процессы разработки и сопровождения ПС, обеспечивая связи внутри коллектива разработчиков ПС и между коллективом разработчиков и менеджерами ПС (software managers)  лицами, управляющими разработкой ПС.

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

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

ГОСТ Р ИСО 9127-94 «Документация пользователя и информация на упаковке для потребительских программных пакетов» – наиболее приглянувшийся мне стандарт из наших. Довольно кратко (весь документ – около 20 страниц) указаны основные требования к составу и содержанию документации пользователя.  ГОСТ Р ИСО/МЭК 15910-2002 «Процесс создания документации пользователя программного средства» — стандарт больше отвечает не на вопрос «Что» должно быть в документе, а «Как» должен создаваться документ. Дополнительно есть подробное описание стиля документа с примером – довольно удобная штука для создания шаблона: один раз запариваешься (и забиваешь в шаблон всё: от выравнивания до формата подписей рисунков), а потом клепаешь документы все одного вида, а не с заголовками разного шрифта.  ГОСТ-ы серии 19.хх – серия ЕСПД (в среднем, документы созданы в 78-м году), в них такие же лаконичные, как в ГОСТ 9127, требования ко многим видам документов. ГОСТ 34.602-89 «Техническое задание на создание автоматизированной системы» — стандарт на ТЗ.

ГОСТ 34.201-89 Виды, комплектность и обозначения документов при создании автоматизированных систем  Это базовый документ, в котором приводится полный перечень документации ГОСТ 34, рекомендации по кодированию документов, к каким стадиям проекта относятся документы (стадии описываются в ГОСТ 34.601-90), а также как их можно объединить между собой.