Пользовательская документация — не самая интересная тема для разработчиков. Однако важно убедиться, что продукт не причинит вреда пользователям — ни физически, ни в плане повреждения их собственности. Утрата данных, выход из строя оборудования и прочие проблемы могут привести к серьезным судебным претензиям.
Эта статья не сделает вас профессиональным техническим писателем, равно как не охватит всех законных требований к продукту. Тем не менее она даст примерное представление о том, как создавать полноценную документацию, которая поможет пользователям эффективно взаимодействовать с софтом.
Статья основана на почти десяти годах моего опыта в сфере технического писательства, а также включает материал, необходимый для не технических писателей.
Определить целевую группу
Прежде чем начать писать документацию, необходимо определить, для кого она будет предназначена? Кто будет использовать продукт?
Я не стану объяснять, как проводить анализ целевой группы, так как вы можете легко найти необходимую информацию в интернете. В целом, вам нужно просто представить потребности пользователей и понять, как они будут отражены в руководстве к продукту.
Введение | Инструкция к программе | Комиссионер.рус
- Если аудитория состоит из людей старшего поколения, то используйте хорошо читаемый разборчивый шрифт.
- Если же она представлена разработчиками, то нет необходимости объяснять базовые шаги в ОС Windows.
- Если вы пишите для дислексиков, то делайте предложения короткими и используйте простые термины.
Этот список далеко не полон и показывает только то, что для написания понятного руководства необходимо понимать его будущих читателей.
Понять, как будет использоваться продукт
Когда с целевой группой пользователей вы определились, нужно понять, как именно они будут работать с продуктом. Хорошая документация всегда должна ориентироваться на пользователя, а не просто объяснять функционал. Технические писатели создают мануалы, ориентированные на задачи, а не на функционал.
Вот два примера, которые помогут выделить отличия этих двух принципов.
- Функционально-ориентированное название главы: “Использование мастера экспорта”.
- Задачно-ориентированное название главы: “Экспортирование данных проекта”.
В данном случае мастер экспорта — это просто инструмент для выполнения задачи, а именно экспорта данных. Пользователи не знают, что для экспорта данных им нужно использовать мастера экспорта. Они будут искать, ориентируясь на задачу, а не функцию.
Разработчики же работают с функционалом, поэтому переключение на восприятие с позиции выполнения задачи может вызывать трудности.
В этом случае рекомендуется спросить себя следующее.
- Что будут делать пользователи с продуктом?
- Почему они его используют? Какова их цель?
Лучше всего будет пригласить группу пользователей и провести с ними обсуждение. Целью будет определить их задачи и, в идеале, дать им название на языке пользователей. Если же возможности собрать группу реальных пользователей у вас нет, то есть еще одно решение: пригласить коллег, которые по своей работе близко с ними связаны (например, продакт-менеджеров, проектных менеджеров, маркетологов или специалистов поддержки).
Инструкция к программе
Создайте список задач в том порядке, в каком пользователи будут их реализовывать. Если вы рассматриваете разные целевые группы с различными задачами, то создайте по одному списку для каждой группы.
Начните с инструкций
Возьмите созданные вами списки задач. Грубо говоря, каждая задача будет одной инструктивной главой руководства. Если список у вас не один, то лучше создать отдельную документацию для каждой целевой группы.
Инструктивная глава дает пользователю пошаговый алгоритм действий.
Советы по написанию инструктивных глав
Вот несколько советов, которые нужно учесть при написании инструктивных глав.
- Начинайте название главы с существительного. Пример: “Экспортирование данных проекта”.
- Структурируйте инструктивные главы в виде нумерованного списка. Каждый этап задачи должен представлять один пункт списка.
- Инструктивная глава не должна превышать 11 шагов. Большее число шагов излишне ее удлинит, снизив удобство чтения. Если в итоге у вас получается длинная глава, то поделите ее на подразделы.
- Описывайте шаги в императивной форме. Пример: чтобы экспортировать данные проекта, нажмите на значок “Экспорт”.
- Не предоставляйте подробной информации о возможности продукта или о том, как он работает. Вместо этого сосредоточьтесь на выполняемых пользователем шагах. Главы с сопутствующей информацией относятся к следующему этапу руководства.
Далее приводится пример того, как должна быть отформатирована и написана инструктивная глава.
Пример инструктивной главы
Добавление сопутствующей информации
После написания инструкций спросите себя: “Что нужно знать пользователям (чего они еще не знают) для выполнения всех этих инструкций?”
Перед каждой инструктивной главой добавляйте концептуальные. Они будут объяснять особенность ПО, необходимую для выполнения инструкций. В примере “Экспортирование данных проекта” одна глава может быть посвящена мастеру экспорта и поддерживаемым форматам данных.
Инструктивная и концептуальная информация строго разделяются, упрощая для пользователя поиск нужной информации. Помните, что большинство пользователей не читают все руководство, а ищут конкретную тему, используя функцию поиска или службу поддержки.
Советы по написанию сопутствующей информации
Вот несколько советов, актуальных при написании концептуальных глав.
- Не добавляйте в заголовках описательные приставки типа “О…” или “Сведения о…”. Называйте только сам принцип или функцию, которую хотите описать. Почему? Когда вы ищете что-либо по теме в интернете, то не вводите “Сведения о затмении”. С большей вероятностью вы будете искать по запросу “Затмение”. Когда пользователи ищут принципиальную информацию, они действуют аналогично, например пишут запрос “Мастер экспорта”.
- Добавляйте только такие концептуальные главы, которые помогут пользователям выполнить инструкцию. Вероятно, вы вложили немало усилий в разработку бэкенда, необходимого для работы конкретной функции. При этом сложности, связанные с ее реализацией, не должны отражаться в документации. Единственное исключение — когда пользователю нужно знать эти детали для выполнения инструкций. Перед написанием концептуальной главы всегда спрашивайте себя: “Зачем пользователю нужно это знать?”.
- Связывайте описательные главы с соответствующими инструктивными и наоборот.
Пример главы с сопроводительной информацией
Добавление справки
Последний компонент — это справка. Справочные главы содержат информацию для поиска в виде таблиц. В этих таблицах вы описываете графический интерфейс пользователя (GUI) и API.
Этот тип информации предназначен для пользователей, которые знакомы с принципом в общем, но хотят почитать о параметре, поле записи, выпадающем меню или других элементах GUI. В первую очередь такие справочные главы ориентированы на опытных пользователей, хотя иногда их читают и новички.
Советы по написанию справочной информации
Примеры справочных глав
Вот и все — у вас получился мануал, ориентированный на нужды пользователей. Конечно же, для создания образцовых мануалов еще многое нужно изучить. Однако с помощью этих основ вы уже сможете выстроить неплохую документацию.
Я не стал детально объяснять, почему рекомендую структурировать и писать руководства именно так. Моей целью было научить вас делать это максимально быстро.
- Используйте проверку орфографии.
- Пишите последовательно.
- Используйте короткие и понятные предложения.
- Используйте как можно меньше слов, только их необходимое количество.
Помните, что мануалы мы читаем не ради удовольствия, а от необходимости.
- 5 вредных привычек неэффективных программистов
- Как написать хороший README: краткий курс
- Успешный релиз ПО: распространенные ошибки перед запуском продукта
Источник: medium.com
Основы написания мануалов при разработке
Пользовательская документация — не самая интересная тема для разработчиков. Однако важно убедиться, что продукт не причинит вреда пользователям — ни физически, ни в плане повреждения их собственности. Утрата данных, выход из строя оборудования и прочие проблемы могут привести к серьезным судебным претензиям.
Эта статья не сделает вас профессиональным техническим писателем, равно как не охватит всех законных требований к продукту. Тем не менее она даст примерное представление о том, как создавать полноценную документацию, которая поможет пользователям эффективно взаимодействовать с софтом.
Статья основана на почти десяти годах моего опыта в сфере технического писательства, а также включает материал, необходимый для не технических писателей.
Определить целевую группу
Прежде чем начать писать документацию, необходимо определить, для кого она будет предназначена? Кто будет использовать продукт?
Я не стану объяснять, как проводить анализ целевой группы, так как вы можете легко найти необходимую информацию в интернете. В целом, вам нужно просто представить потребности пользователей и понять, как они будут отражены в руководстве к продукту.
- Если аудитория состоит из людей старшего поколения, то используйте хорошо читаемый разборчивый шрифт.
- Если же она представлена разработчиками, то нет необходимости объяснять базовые шаги в ОС Windows.
- Если вы пишите для дислексиков, то делайте предложения короткими и используйте простые термины.
Этот список далеко не полон и показывает только то, что для написания понятного руководства необходимо понимать его будущих читателей.
Понять, как будет использоваться продукт
Когда с целевой группой пользователей вы определились, нужно понять, как именно они будут работать с продуктом. Хорошая документация всегда должна ориентироваться на пользователя, а не просто объяснять функционал. Технические писатели создают мануалы, ориентированные на задачи, а не на функционал.
Вот два примера, которые помогут выделить отличия этих двух принципов.
- Функционально-ориентированное название главы: “Использование мастера экспорта”.
- Задачно-ориентированное название главы: “Экспортирование данных проекта”.
В данном случае мастер экспорта — это просто инструмент для выполнения задачи, а именно экспорта данных. Пользователи не знают, что для экспорта данных им нужно использовать мастера экспорта. Они будут искать, ориентируясь на задачу, а не функцию.
Разработчики же работают с функционалом, поэтому переключение на восприятие с позиции выполнения задачи может вызывать трудности.
В этом случае рекомендуется спросить себя следующее.
- Что будут делать пользователи с продуктом?
- Почему они его используют? Какова их цель?
Лучше всего будет пригласить группу пользователей и провести с ними обсуждение. Целью будет определить их задачи и, в идеале, дать им название на языке пользователей. Если же возможности собрать группу реальных пользователей у вас нет, то есть еще одно решение: пригласить коллег, которые по своей работе близко с ними связаны (например, продакт-менеджеров, проектных менеджеров, маркетологов или специалистов поддержки).
Создайте список задач в том порядке, в каком пользователи будут их реализовывать. Если вы рассматриваете разные целевые группы с различными задачами, то создайте по одному списку для каждой группы.
Начните с инструкций
Возьмите созданные вами списки задач. Грубо говоря, каждая задача будет одной инструктивной главой руководства. Если список у вас не один, то лучше создать отдельную документацию для каждой целевой группы.
Инструктивная глава дает пользователю пошаговый алгоритм действий.
Советы по написанию инструктивных глав
Вот несколько советов, которые нужно учесть при написании инструктивных глав.
- Начинайте название главы с существительного. Пример: “Экспортирование данных проекта”.
- Структурируйте инструктивные главы в виде нумерованного списка. Каждый этап задачи должен представлять один пункт списка.
- Инструктивная глава не должна превышать 11 шагов. Большее число шагов излишне ее удлинит, снизив удобство чтения. Если в итоге у вас получается длинная глава, то поделите ее на подразделы.
- Описывайте шаги в императивной форме. Пример: чтобы экспортировать данные проекта, нажмите на значок “Экспорт”.
- Не предоставляйте подробной информации о возможности продукта или о том, как он работает. Вместо этого сосредоточьтесь на выполняемых пользователем шагах. Главы с сопутствующей информацией относятся к следующему этапу руководства.
Далее приводится пример того, как должна быть отформатирована и написана инструктивная глава.
Пример инструктивной главы
Добавление сопутствующей информации
После написания инструкций спросите себя: “Что нужно знать пользователям (чего они еще не знают) для выполнения всех этих инструкций?”
Перед каждой инструктивной главой добавляйте концептуальные. Они будут объяснять особенность ПО, необходимую для выполнения инструкций. В примере “Экспортирование данных проекта” одна глава может быть посвящена мастеру экспорта и поддерживаемым форматам данных.
Инструктивная и концептуальная информация строго разделяются, упрощая для пользователя поиск нужной информации. Помните, что большинство пользователей не читают все руководство, а ищут конкретную тему, используя функцию поиска или службу поддержки.
Советы по написанию сопутствующей информации
Вот несколько советов, актуальных при написании концептуальных глав.
- Не добавляйте в заголовках описательные приставки типа “О…” или “Сведения о…”. Называйте только сам принцип или функцию, которую хотите описать. Почему? Когда вы ищете что-либо по теме в интернете, то не вводите “Сведения о затмении”. С большей вероятностью вы будете искать по запросу “Затмение”. Когда пользователи ищут принципиальную информацию, они действуют аналогично, например пишут запрос “Мастер экспорта”.
- Добавляйте только такие концептуальные главы, которые помогут пользователям выполнить инструкцию. Вероятно, вы вложили немало усилий в разработку бэкенда, необходимого для работы конкретной функции. При этом сложности, связанные с ее реализацией, не должны отражаться в документации. Единственное исключение — когда пользователю нужно знать эти детали для выполнения инструкций. Перед написанием концептуальной главы всегда спрашивайте себя: “Зачем пользователю нужно это знать?”.
- Связывайте описательные главы с соответствующими инструктивными и наоборот.
Пример главы с сопроводительной информацией
Добавление справки
Последний компонент — это справка. Справочные главы содержат информацию для поиска в виде таблиц. В этих таблицах вы описываете графический интерфейс пользователя (GUI) и API.
Этот тип информации предназначен для пользователей, которые знакомы с принципом в общем, но хотят почитать о параметре, поле записи, выпадающем меню или других элементах GUI. В первую очередь такие справочные главы ориентированы на опытных пользователей, хотя иногда их читают и новички.
Советы по написанию справочной информации
Примеры справочных глав
Вот и все — у вас получился мануал, ориентированный на нужды пользователей. Конечно же, для создания образцовых мануалов еще многое нужно изучить. Однако с помощью этих основ вы уже сможете выстроить неплохую документацию.
Я не стал детально объяснять, почему рекомендую структурировать и писать руководства именно так. Моей целью было научить вас делать это максимально быстро.
- Используйте проверку орфографии.
- Пишите последовательно.
- Используйте короткие и понятные предложения.
- Используйте как можно меньше слов, только их необходимое количество.
Помните, что мануалы мы читаем не ради удовольствия, а от необходимости.
- 5 вредных привычек неэффективных программистов
- Как написать хороший README: краткий курс
- Успешный релиз ПО: распространенные ошибки перед запуском продукта
- ТЭГИ
- Software Development
Источник: nuancesprog.ru
Руководство пользователя
Руководство пользователя – это основной документ в составе эксплуатационной документации на автоматизированную систему (ГОСТ 34). Очевидно ли это?
Назначение руководства пользователя
Цель создания документа заключается в том, чтобы предоставить пользователю возможность самостоятельно решать свои прикладные задачи с помощью системы. Этой цели может служить и введение в предметную область, и ознакомление со всеми возможностями программы, и описание конкретных процедур решения задач, и приведение различных инструкций. Иногда Руководство пользователя больше похоже на справочник, к которому можно обращаться в процессе работы, а иногда – на учебник, который позволяет изучить принципы работы с программой и ее возможности, а затем применять их на практике.
Состав типового руководства пользователя
Конкретный подход к написанию определяется многими факторами:
– назначением программы и областью ее применения;
– количеством разнообразных вариантов использования.
Принимая во внимание все различия и особенности, сложно привести структуру любого Руководства пользователя к одному виду. Тем не менее, РД 50-34.698 предлагает нам такой список разделов:
– Введение, где указывают область применения ПО, краткое описывают его возможности, требуемый уровень знаний пользователя и список документов, которые необходимо изучить помимо настоящего руководства;
– Назначение и условия применения, где описывают виды деятельности и функции, которые автоматизированы и условия, при соблюдении которых автоматизация используется;
– Подготовка к работе, где описывают комплектность дистрибутива, порядок установки и загрузки программы, а также способ проверки ее работоспособности;
– Описание операций, представляет собой основной раздел, где описывают функции программы, процессы работы с данными, выполнение конкретных задач пользователя;
– Аварийные ситуации, где описывают действия в нештатных ситуациях – сбоях в программе, ошибок в данных и т.д.;
– Рекомендации по освоению, где приводят методические рекомендации по изучению программы и примеры использования.
Данная структура может меняться и дополняться – например, основной раздел часто разбивают на несколько значимых разделов по группам функций или задач, также в современных системах нередко добавляют раздел Интерфейс пользователя, где описывают взаимодействие пользователя с программой с примерами и снимками экрана.
Стандарты для руководства пользователя
Стоимость разработки руководства пользователя
РП на автоматизированную систему
Грамотно написанное Руководство пользователя может сэкономить значительное количество времени на обучение и адаптацию пользователя к программе, а также снизить количество ошибок в работе что, в свою очередь, повышает экономическую эффективность системы. Если вы не хотите вникать во все тонкости создания Руководства пользователя, но хотите иметь полный, качественный и полезный документ – обратитесь в компанию ТехРайтКонсалт, и мы применим весь наш опыт и знания для решения вашей задачи по доступной цене!
Возможно, вас также заинтересует:
Источник: techwrconsult.com