Ключ к написанию хорошей документации: тестирование инструкций

25.09.2017

Всем нам попадались инструкции, в которых было или сложно найти то, что нужно, или была куча непонятных терминов, или даже отсутствовали какие-то шаги в последовательности действий. А некоторые из нас и сами писали такие инструкции ? Чтобы этого избежать, необходимо проводить тестирование документации как неотъемлемой части разрабатываемых продуктов. Статья посвящена организации тестирования документации на предприятии и проблемам, которые при этом возникают. Автор: Том Джонсон, технический писатель из США.

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

О тестировании

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

Прохождение каждого шага в документации от своего лица, как технического писателя, крайне важно для создания хорошей документации. Однако чем сложнее структура документа, тем сложнее пройти все шаги. Особенно в случае с документацией для разработчиков, эта задача не тривиальна. Но она является неотъемлемой частью создания и пользовательской документации тоже. Читать дальше…

Элементарно, мой дорогой Ватсон: Редактор как Детектив

23.08.2017

Представляем вашему вниманию статью о работе редактора. Автор: Джефф Харт, сейчас работающий на фрилансе научным редактором, а ранее в таких организациях как IBM, Лесничество Канады и Канадский лесной институт.

В классической детективной истории отважный сыщик начинает расследования истинной истории события — в литературе, предположим, об убийстве или воровстве. Но при редактировании мы пытаемся обнаружить истинную историю автора и реконструировать её, насколько это возможно, в единое целое, которое уложено логически и поучительно для читателя. (Мы также в какой-то степени раскрываем преступления против языка). Только понимая цепочку событий, детектив может понять, что привело к преступлению.

Если без шуток, редакторы редко раскрывают настоящие преступления, но процесс редакторского «детектирования» несёт в себе удивительную схожесть с раскрытием криминальных дел. В частности, прежде чем автор решится сесть за рукопись, должны совпасть три главных составляющих:

• мотив
• благоприятная возможность
• средства

Читать дальше…

Анализ аудитории (часть 2)

28.12.2016

На прошлой неделе мы говорили о том, как проанализировать целевую аудиторию своего документа. Сегодня мы расскажем о том, что делать дальше. Когда вы определились с ЦА, текст необходимо подгонять под неё. О приёмах подстройки под ЦА – в сегодняшней статье.

Адаптация под аудиторию

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

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

• Добавляйте информацию, необходимую вашим читателям для понимания.

Проверьте, не отсутствует ли какая-либо конкретная ключевая информация — например, критические последовательности шагов в наборе инструкций; важная дополнительная информация, которая помогает начинающим понять основную тему; определение ключевых терминов. (См. раздел об идеях для контента для более подробной информации). Читать дальше…

Анализ аудитории (часть 1)

23.12.2016

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

Аудитория технического текста — или любого другого, если на то пошло — определяется потенциальным читателем или читателями. Для большинства технических писателей это самый важный вопрос при планировании, написании и рецензировании документа. Вы «адаптируете» свой документ, чтобы удовлетворять потребностям, интересам и бэкграунду будущих читателей вашего документа. Читать дальше…