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