Хорошая документация по программному обеспечению, будь то техническая документация для программистов и тестировщиков, техническая документация для внутренних пользователей или руководства и файлы справки для конечных пользователей, поможет пользователям понять особенности и функции программного обеспечения. Хорошая документация - это конкретная, ясная и актуальная документация, в которой содержится вся необходимая пользователю информация. Эта статья поможет вам написать документацию по программному обеспечению для технических и конечных пользователей.
Шаг
Метод 1 из 2: Написание программной документации для технических пользователей
Шаг 1. Знайте, какую информацию включить
Документ спецификации используется в качестве справочного руководства для разработчиков интерфейсов, программистов, пишущих код, и тестировщиков, проверяющих производительность программного обеспечения. Информация, которую необходимо включить, будет зависеть от создаваемой программы, но может включать следующее:
- Важные файлы в приложении, такие как файлы, созданные командой разработчиков, базы данных, к которым осуществляется доступ во время работы программы, и сторонние приложения.
- Функции и подпрограммы, включая объяснение использования функции / подпрограммы, входных и выходных значений.
- Программные переменные и константы, и как они используются.
- Общая структура программы. Для программ на основе дисков вам может потребоваться описать каждый модуль и библиотеку. Или, если вы пишете руководство для веб-программы, вам может потребоваться объяснить, какие файлы используются на каждой странице.
Шаг 2. Решите, какой уровень документации должен присутствовать и отделяться от программного кода
Чем больше технической документации включено в программный код, тем проще будет его обновлять и поддерживать, а также объяснять различные версии программы. Как минимум, документация в программном коде должна включать использование функций, подпрограмм, переменных и констант.
- Если ваш исходный код длинный, вы можете написать документацию в файле справки, который затем можно будет индексировать или искать по определенным ключевым словам. Отдельные файлы документации полезны, если логика программы разбита на несколько страниц и включает файлы поддержки, такие как веб-приложение.
- Некоторые языки программирования (такие как Java, Visual Basic. NET или C #) имеют свои собственные стандарты документации кода. В таких случаях следуйте стандартной документации, которая должна быть включена в исходный код.
Шаг 3. Выберите соответствующий инструмент документации
В некоторых случаях инструмент документации определяется используемым языком программирования. Языки C ++, C #, Visual Basic, Java, PHP и другие имеют свои собственные инструменты документации. Однако в противном случае используемые инструменты будут зависеть от необходимой документации.
- Текстовый процессор, такой как Microsoft Word, подходит для создания текстовых файлов документов, если документация краткая и простая. Для создания длинной документации со сложным текстом большинство технических писателей выбирают специализированный инструмент документации, такой как Adobe FrameMaker.
- Файлы справки для документирования исходного кода могут быть созданы с помощью программы-генератора файлов поддержки, такой как RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare или HelpLogix.
Метод 2 из 2: Написание программной документации для конечных пользователей
Шаг 1. Знайте бизнес-причины, лежащие в основе создания руководства
Хотя основная причина документации программного обеспечения - помочь пользователям понять, как использовать приложение, существует несколько других причин, которые могут лежать в основе создания документации, например, помощь отделу маркетинга в продаже приложения, улучшение имиджа компании и сокращение объема технической поддержки. расходы. В некоторых случаях требуется документация для соблюдения нормативных требований или других требований законодательства.
Однако документация не может заменить интерфейс. Если приложение требует для работы большого количества документации, оно должно быть более интуитивно понятным
Шаг 2. Знайте целевую аудиторию документации
Как правило, пользователи программного обеспечения обладают ограниченными компьютерными знаниями, помимо используемых ими приложений. Есть несколько способов удовлетворить их потребности в документации:
- Обратите внимание на название пользователя программного обеспечения. Например, системный администратор обычно разбирается в различных компьютерных приложениях, а секретарь знает только приложения, которые он использует для ввода данных.
- Обратите внимание на пользователей программного обеспечения. Хотя их должности обычно совместимы с выполняемыми задачами, на этих должностях могут быть разные нагрузки в зависимости от места работы. Проведя собеседование с потенциальными пользователями, вы сможете узнать, верна ли ваша оценка их должности.
- Обратите внимание на существующую документацию. Документация и спецификации функциональных возможностей программного обеспечения могут показать, что пользователям необходимо знать для их использования. Однако имейте в виду, что пользователям может быть неинтересно знать "внутренности" программы.
- Знайте, что нужно для выполнения задачи и что требуется, прежде чем вы сможете ее выполнить.
Шаг 3. Определите подходящий формат для документации
Документация к программному обеспечению может быть представлена в 1 или 2 форматах: справочники и руководства. Иногда хорошим решением является объединение двух форматов.
- Справочные форматы используются для описания всех функций программного обеспечения, таких как кнопки, вкладки, поля и диалоговые окна, а также их работы. Некоторые файлы справки написаны в этом формате, особенно те, которые зависят от контекста. Когда пользователь нажимает на Справку на определенном экране, пользователь получает соответствующую тему.
- Формат руководства используется для объяснения того, как что-то делать с программным обеспечением. Руководства обычно находятся в печатном виде или в формате PDF, хотя некоторые страницы справки также включают инструкции о том, как делать определенные вещи. (Как правило, ручные форматы не зависят от контекста, но могут быть связаны из контекстно-зависимых тем). Справочники обычно имеют форму руководства с кратким описанием задач, которые необходимо выполнить, и руководством, отформатированным по шагам.
Шаг 4. Определитесь с типом документации
Программная документация для пользователей может быть упакована в одном или нескольких из следующих форматов: печатные руководства, файлы PDF, файлы справки или онлайн-справка. Каждый тип документации предназначен для того, чтобы показать вам, как использовать функции программного обеспечения, будь то руководство или учебное пособие. Онлайн-документация и страницы справки могут также включать демонстрационные видеоролики, текст и статические изображения.
Файлы онлайн-справки и поддержки должны быть проиндексированы и доступны для поиска по ключевым словам, чтобы пользователи могли быстро найти нужную информацию. Хотя приложение-генератор файлов справки может создавать индекс автоматически, все же рекомендуется создавать индекс вручную, используя часто используемые ключевые слова
Шаг 5. Выберите соответствующий инструмент документации
Печатные руководства или PDF-файлы могут быть созданы с помощью текстового редактора, такого как Word, или расширенного текстового редактора, такого как FrameMaker, в зависимости от длины и сложности файла. Файлы справки могут быть написаны с помощью программы создания файлов справки, такой как RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix или HelpServer.
подсказки
- Текст документации к программе должен быть структурирован таким образом, чтобы его было легко читать. Поместите изображение как можно ближе к соответствующему тексту. Разбейте документацию по разделам и темам логически. Каждый раздел или тема должны описывать конкретную проблему, как задачи, так и особенности программы. Связанные вопросы можно объяснить с помощью ссылок или списков литературы.
- Каждый из инструментов документации, описанных в этой статье, может быть дополнен программой для создания снимков экрана, такой как SnagIt, если для вашей документации требуется несколько снимков экрана. Как и в любой другой документации, вы также должны включать снимки экрана, чтобы помочь объяснить, как работает приложение, а не «заманивать» пользователя.
- Очень важно уделять внимание стилю, особенно если вы пишете документацию по программному обеспечению для конечных пользователей. Обращайтесь к пользователям с местоимением «вы» вместо «пользователь».
