Документация – такая штука, к которой мало кто питает тёплые чувства: скучно, занудно, однообразно. И, тем не менее, иногда не возникает сомнений в её необходимости: ведь кому-то после вас этим пользоваться или, тем паче, модифицировать. И тогда появляется вопрос: как сделать документацию правильно? Существует тьма статей на тему «как писать документацию», но если вы решили взяться за неё в первый раз, то в новой для вас области не сразу понятно, дело ли пишет автор, или отсебятину выдумывает.
Для того чтобы сформировать своё мнение без перелопачивания статей, можно пойти двумя путями: довериться некому авторитету или посмотреть в стандарты – уж там-то с наибольшей вероятностью проблему обдумали со всех сторон.
Кто-то может сказать «а-а, стандарты! они ещё более адово скучные, чем сама документация!». Ну, не будем врать, есть немного :) Но если у вас документ в электронном формате – найти необходимое не составляет труда. И кроме того, ну надо же размочить раздел стандарты уже, а то висит пустой, даже обидно.
Наши.
Обратимся сначала к ГОСТ-ам. Они расстраивают датами разработки (впрочем, похоже, за эти годы в документировании не многе изменилось) и радуют бесплатностью.
ГОСТ Р ИСО 9127-94 «Документация пользователя и информация на упаковке для потребительских программных пакетов» – наиболее приглянувшийся мне стандарт из наших. Довольно кратко (весь документ – около 20 страниц) указаны основные требования к составу и содержанию документации пользователя.
Официальная страница. Скачать PDF.
ГОСТ Р ИСО/МЭК 15910-2002 «Процесс создания документации пользователя программного средства» — стандарт больше отвечает не на вопрос «Что» должно быть в документе, а «Как» должен создаваться документ. Дополнительно есть подробное описание стиля документа с примером – довольно удобная штука для создания шаблона: один раз запариваешься (и забиваешь в шаблон всё: от выравнивания до формата подписей рисунков), а потом клепаешь документы все одного вида, а не с заголовками разного шрифта.
Официальная страница. Скачать PDF.
ГОСТ-ы серии 19.хх – серия ЕСПД, страсть, какая древняя (в среднем, документы созданы в 78-м году), но зато такие же лаконичные, как в ГОСТ 9127, требования ко многим видам документов.
Ознакомиться.
ГОСТ 34.602-89 «Техническое задание на создание автоматизированной системы» — стандарт на ТЗ. Спасибо Jazzist.
Буржуйские.
Не было предела моему возмущению, когда я узнала, что международные стандарты не бесплатные. Это как правила дорожного движения сделать платными. Но в принципе, может и резонно: организации-то не государственные. Хотят – могут и деньги брать за свою работу. К счастью, многие стандарты можно скачать по-привычному, по-пиратски.
IEEE Std 1063-2001 «IEEE Standard for Software User Documentation» — в документе обозначены требования к структуре, содержимому и формату инструкций пользователя.Официальная страница.
IEEE Std 1016-1998 «IEEE Recommended Practice for Software Design Descriptions» — рекомендации к документам, описывающим архитектуру программного обеспечения, то бишь к техническому описанию.
Официальная страница.
Особливо понравилась табличка-экстракт основного содержания документа (здесь вольный перевод):
| Тип обзора | Содержание | Атрибуты | Примеры представления |
|---|---|---|---|
| Декомпозиция | Разбиение системы на структурные составляющие | Определение, тип, назначение, функции, зависимые сущности | Иерархическая диаграмма декомпозиции, словесное описание. |
| Описание зависимостей | Описание связей между сущностями и системными ресурсами. | Определение, тип, назначение, зависимости, ресурсы. | Структурные схемы, диаграммы потоков данных, схемы транзакций. |
| Описание интерфейса | Список всего, что может потребоваться знать проектировщику, программисту или тестеру для того чтобы использовать структурные составляющие системы. | Определение, функции, интерфейсы. | Файлы интерфейса, таблицы параметров. |
| Описание деталей | Описание внутреннего устройства частей сущности. | Определение, обработка данных, данные. |
Блок-схемы, N-S диаграммы, PDL |
ISO/IEC FDIS 18019:2004 «Guidelines for the design and preparation of user documentation for application software» — рекомендации по созданию документации пользователя. Так сказать, советы «хозяйке на заметку». Довольно приятное руководство с большим количеством примеров (имхо, больше подходит для чтения до или в самом начале создания документации, так как подходит к процессу основательно, от самого планирования). Также в приложениях есть чеклисты «что не забыть сделать в процессе разработки документации» и «что должно быть в документе»Официальная страница.
ISO/IEC 26514:2008 «Requirements for designers and developers of user documentation» — довольно свежий и, судя по содержанию, полезный документ. Но, как раз, видимо, ввиду его свежести, этот стандарт нигде не найти бесплатно. По крайней мере, мне этого сделать не удалось.Официальная страница.
Это были стандарты, наиболее тесно связанные с документированием. Они могут пригодиться как начинающему техпису, так и, например, фрилансеру, который «и швец, и жнец, и на дуде игрец».
Уточнения, дополнения и полезные ссылки приветствуются)
UPD: очень познавательный комментарий, спасибо lkochetova
UPD1: совесть меня таки замучила, и в статье больше не будет висеть прямых ссылок на скачивание стандартов, не распространяемых свободно. Если они вам понадобятся — нагуглить не составит труда.
UPD2: также смотрите статью Документирование по ГОСТ 34* — это просто с подробным разбором отечественных стандартов на проектную документацию.
