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

25.09.2017

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

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

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

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

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

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

23.08.2017

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

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

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

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

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

Адвокат пользователя: пользователи глупые… или нет

08.12.2016

Если кто-то не понял вашу инструкцию, значит он глуп? Или же причина в вас? Разберёмся вместе с Филом Девисом, техническим писателем с 20-летним стажем из Integral Development Corp., США.

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

— Дуглас Адамс, Последняя возможность увидеть

Назвать кого-либо «незнающим» — бесполезное суждение. Нет ничего постыдного в том, чтобы быть незнающим, если вы признаёте это и готовы при возможности изучить. Как технический писатель я люблю давать своим пользователям эту возможность.

«Глупый», с другой стороны, это преднамеренное незнание. Глупость исключает обучение.

Пользователи глупые. Они не хотят приложить даже незначительные усилия для собственного образования. Иногда пользователи настолько глупы, что действуют против собственных интересов, иногда впечатляюще опасными способами.

Глупость приходит во множестве обличий. Некоторые можно распознать: Читать дальше…

Качество писательства никогда не сможет быть лучше качества исследования

21.10.2016

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

От редактора: Следующая статья написана Германом Хольтцем (Herman Holtz) является частью «классической» коллекции статей, которые прошли проверку времени, независимо от того, сколько появилось и ещё появится новых технологий.

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

Адвокат пользователя. Осторожнее со словами

05.05.2016

Нил Каплан, автор серии «Адвокат пользователя», отличается от многих технических писателей тем, что пишет не для компании, не для того, чтобы просто что-то написать, а для своего пользователя. Клиентоориентированность сегодня стоит во главе угла любого бизнеса, поэтому предлагаем ознакомиться – а в идеале и перенять – некоторые из принципов такого подхода.

Я хотел бы поговорить о словах, которыми мы пользуемся. Мы технические коммуникаторы, и наш основной инструмент общения с аудиторией – слова. Создаём ли мы руководство пользователя, онлайн-справку, всплывающие подсказки или надписи в интерфейсе. Даже обучающее видео – это комбинация картинок и слов. Читать дальше…

Быстрый, простой и доступный способ инвентаризации веб-контента

29.04.2016

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

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

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

Адвокат пользователя: Наш технический контент клиентоориентирован? Да!

16.03.2016

Технический контент компании, производящей программные продукты и устройства, должен идеально сочетаться со всем контентом компании. Что это даёт и как этого добиться, рассказывает Нил Каплан в рубрике «Адвокат пользователя». Нил Каплан – менеджер по повышению квалификации в Condeco Software, Сан-Хосе (США), отвечает за изготовление, поставку и управление обучающим контентом и за документацию к продуктам Condeco.

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

Алгоритмы: Отделение контента от форматирования

10.03.2016

Статья входит в цикл «Понимание и применение структурированного писательства».

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

На этой стадии этой серии статей я собираюсь начать рассматривать алгоритмы структурированного писательства. Алгоритм — это формализованный метод для выполнения задачи. Мы часто связываем алгоритмы с компьютерами, т.к. для того, чтобы заставить компьютер что-либо сделать, мы должны формализовать алгоритм и представить его в виде программы. Но люди так же могут исполнять алгоритмы. Это одна из причин, почему мы обращаемся к структурированному писательству, с тем, чтобы передать трудоёмкие и обременительные алгоритмы писательства и публикации машинам. Читать дальше…

Насколько глобален ваш английский: 8 способов писать просто и много экономить

03.03.2016

Статья Марсии Рифер Джонстон о том, как писать на английском, чтобы упростить жизнь сразу многим — неанглоязычным читателям, англоязычным читателям, переводчикам, людям с проблемами со зрением, экспертам по предмету — и заодно сэкономить солидную часть бюджета компаниям, которые переводят свой контент на другие языки. Кстати, в нашем блоге уже была статья этого же автора также на лингвистическую тему.

Какого *&^! это значит? Мы все хоть раз говорили так. Ладно, мы все хоть раз говорили что-то вроде этого. Фактически вы можете не знать, что означает *&^!. Это не однозначно. Даже если я сама не знаю, какое слово должно быть здесь, как же переводчик узнал бы, что с этим делать?

Зачем делать работу вашего переводчика сложнее – и дороже – чем она должна быть? Почему бы не исключить двусмысленности сразу же? Читать дальше…

Качество в структурированном писательстве

03.02.2016

Статья входит в цикл «Понимание и применение структурированного писательства».

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

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

Роботы, которые читают

Машины действительно всё лучше и лучше понимают человеческий язык. Подход, который называется Глубинным обучением, всё больше становится основной технологией для таких компаний как Facebook, Google и Baidu как для понимания языка, так и для распознавания речи. Читать дальше…