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

16.07.2014

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

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

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

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

При этом ни в коем случае документация не должна быть компенсацией за плохой дизайн интерфейса. Если для объяснения экрана приложения нужны пачки документов, лучше сделать экран более интуитивным.

2. Понимайте, для какой аудитории вы пишете документацию. В большинстве случаев пользователи программного обеспечения мало знают о компьютерах вне задач приложения, которые они используют. Есть несколько способов определить, как удовлетворить их потребности в вашей документации.

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

Определите задачи, необходимые для выполнения работы, и задачи, которые нужно выполнить до выполнения этих задач.

3. Определите подходящий формат(ы) для документации. Документация к программному обеспечению может быть создана в 1 из 2 форматов – справочном руководстве и руководстве пользователя. Иногда сочетание форматов является лучшим подходом.

• Формат справочного руководства посвящён объяснению индивидуальных особенностей программного приложения (кнопки, вкладки, поля и диалоговые окна) и тому, как они работают. Многие файлы справки написаны в этом формате, в частности контекстно-зависимая справка, которая отображает соответствующую тему всякий раз, когда пользователь нажимает кнопку Справка на конкретном экране.
• Формат руководства пользователя объясняет, как использовать программное обеспечение для выполнения конкретной задачи. Инструкции часто бывают в формате печатных руководств или PDF-файлов, хотя некоторые файлы справки включают темы о том, как выполнять конкретные задачи. (Эти разделы справки, как правило, не контекстно-зависимы, хотя на них могут ссылаться контекстно-зависимые разделы). Инструкции часто принимают форму учебного пособия с кратким изложением решаемых задач во введении и инструкциями в виде пронумерованных шагов.

4. Решите, какую форму (ы) примет документация. Документация по программному обеспечению для конечных пользователей может быть в одной или нескольких из большого количества форматов: печатные руководства, PDF-документы, файлы справки или интерактивная справка. Каждая форма призвана показать пользователю, как использовать любую функции программы, будь то в виде пошагового руководства или учебного пособия; в случае с файлами справки и онлайн-справки наряду с текстом и простой графикой может включаться видео.

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

5. Выберите соответствующий инструмент документирования. Печатные документы и руководства в формате PDF можно создавать с помощью программы обработки текстов, как Word, или сложного текстового редактора, например, FrameMaker, в зависимости от их длины и сложности. Файлы справки можно писать с помощью инструментов написания справки, таких как RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix или HelpServer.

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

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