Как писать документацию к программному обеспечению (часть 1)

14.07.2014

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

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

Метод 1 из 2: Пишем документацию для технических специалистов

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

• Ключевые файлы приложения. Они могут включать файлы, созданные командой разработчиков, базы данных, доступ к которым осуществляется при выполнении программы, и утилиты третьих сторон.
• Функции и подпрограммы. Они включают в себя объяснение того, что делает каждая функция или подпрограмма, в том числе диапазон входных и выходных значений.
• Переменные и константы программы, и то, как они используются в приложении.
• Общая структура программы. Для дисковой версии приложения это может быть описание отдельных модулей и библиотек программы. Для веб-приложения – указание, какие страницы ссылаются на какие файлы.

2. Решите, сколько документации нужно включить в программный код, и сколько должно быть отдельно от него. Чем больше технической документации разрабатывается внутри исходного кода программы, тем легче будет обновлять и поддерживать её вместе с кодом, как и документировать различные версии оригинального приложения. Как минимум, документация в исходном коде должна объяснять назначение функций, подпрограмм, переменных и констант.

• Если исходный код особенно длинный, его можно задокументировать в виде файла справки, который можно проиндексировать или запустить поиск по ключевым словам. Это особенно удобно для приложений, где логика программы разбита на несколько страниц и включает в себя ряд дополнительных файлов, как определённые веб-приложения.
• Некоторые языки программирования, такие как Java и .NET Framework (VisualBasic .NET, C#), имеют свои собственные стандарты для документирования кода. В этих случаях следуйте стандартам относительно того, какую часть документации нужно включить в исходный код.

3. Выберите соответствующий инструмент документирования. В какой-то степени он обусловлен языком, на котором код написан, будь то C++, C#, Visual Basic, Java или PHP, так как для этих и других языков существуют конкретные инструменты. В других случаях инструмент для использования зависит от типа необходимых документов.

• Текстовых редакторов от Microsoft Word достаточно для создания отдельных текстовых файлов документации, при условии, что документация довольно кратка и проста. Для длинных и сложных текстовых файлов многие технические писатели предпочитают специальный инструмент документирования, например Adobe FrameMaker.
• Файлы справки для документирования исходного кода можно создавать любым инструментом написания справки: RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare или HelpLogix.

(продолжение следует)

Источник: How to Write Software Documentation

Тэги: инструкции, инструменты, советы