Публикации
Ключ к написанию хорошей документации: тестирование инструкций
25.09.2017Всем нам попадались инструкции, в которых было или сложно найти то, что нужно, или была куча непонятных терминов, или даже отсутствовали какие-то шаги в последовательности действий. А некоторые из нас и сами писали такие инструкции ? Чтобы этого избежать, необходимо проводить тестирование документации как неотъемлемой части разрабатываемых продуктов. Статья посвящена организации тестирования документации на предприятии и проблемам, которые при этом возникают. Автор: Том Джонсон, технический писатель из США.
Написание хорошей документации требует от вас создания тестовой среды и тестирования всего, что описано в инструкциях – тестирования именно вами и тестирования на уровне пользователя. Тестирование инструкции может быть трудоёмким и заковыристым процессом, особенно с документацией для разработчиков. Увидеть сделанные пробелы и допущения трудно. Но тестирование инструкций даёт вам доступ к инсайтам, которые сделают вашу документацию намного более точной и полезной.
О тестировании
Недавно в гонке за дедлайном мне пришлось поступиться одним из принципов технического документирования, который я ценю больше всего: тестированием каждого шага в моей документации, особенно от лица пользователя.
Прохождение каждого шага в документации от своего лица, как технического писателя, крайне важно для создания хорошей документации. Однако чем сложнее структура документа, тем сложнее пройти все шаги. Особенно в случае с документацией для разработчиков, эта задача не тривиальна. Но она является неотъемлемой частью создания и пользовательской документации тоже. Читать дальше…
Адвокат пользователя: пользователи глупые… или нет
08.12.2016
Если кто-то не понял вашу инструкцию, значит он глуп? Или же причина в вас? Разберёмся вместе с Филом Девисом, техническим писателем с 20-летним стажем из Integral Development Corp., США.
Человеческие существа, которые практически уникальны в том, что имеют способность учиться на опыте других, также поразительны в своем абсолютном нежелании делать это.
— Дуглас Адамс, Последняя возможность увидеть
Назвать кого-либо «незнающим» — бесполезное суждение. Нет ничего постыдного в том, чтобы быть незнающим, если вы признаёте это и готовы при возможности изучить. Как технический писатель я люблю давать своим пользователям эту возможность.
«Глупый», с другой стороны, это преднамеренное незнание. Глупость исключает обучение.
Пользователи глупые. Они не хотят приложить даже незначительные усилия для собственного образования. Иногда пользователи настолько глупы, что действуют против собственных интересов, иногда впечатляюще опасными способами.
Глупость приходит во множестве обличий. Некоторые можно распознать: Читать дальше…
Чат гендиректоров: Будущее контента с Майклом Розински
14.10.2016
Сегодня мы обсуждаем будущее контента с Майклом Розински (Michael Rosinski), генеральным директором Astoria Software, облачной компонентной системы управления контентом (CCMS). Розински, ветеран области управления контентом, разговаривает со Скоттом Абелем (Scott Abel), The Content Wrangler, об инновациях, информационных технологиях и о том, как искусственный интеллект повлияет на контент и тех, кто его производит.
Скотт: Майкл, вы человек, окружённый технологиями круглосуточно – ставлю, что вы видите здравый смысл в грядущих больших изменениях. Помогите нам разобраться. Как гендиректор технологической компании, что вы считаете наиболее захватывающими инновациями в плоскости контента?
Майкл: Отличный вопрос. Я верю, что наиболее захватывающая инновация в мире контента – когнитивные информационные технологии. Почему? Потому что традиционные информационные технологии хотя и впечатляющие, в то же время несколько идиотские. Нынешнее программное обеспечение для компьютеров может составлять таблицы и вычислять, хранить, управлять и доставлять файлы быстрее человека. И несмотря на то, что компьютеры намного лучше запоминают детали, они не могут предоставлять многие возможности относительно контента, необходимые современным компаниям. Однако вскоре это изменится. Читать дальше…
Почему люди забывают наш контент (и что с этим делать)
20.05.2016
Мы часто даём советы, как сделать контент лучше, как улучшить восприятие или добавить интересных деталей. Но есть и ещё одна проблема, на которую стоит обратить внимание – люди не помнят, что прочитали на прошлой неделе, а порой и пару часов назад. Наверняка вы замечали подобное и за собой – покупаешь новую технику, тщательно изучаешь инструкцию, а через несколько дней всё забываешь и начинаешь спрашивать у знакомых и родных, так как снова доставать документацию почему-то совершенно не хочется. Почему?
Почему люди забывают наш контент?
Одной из наиболее очевидных причин, почему люди забывают наш контент, является информационная перегрузка. Читать дальше…
Вторая волна DITA
19.02.2016
Некоторое время назад в нашем блоге частенько появлялись статьи о стандарте DITA. Например, эта — ключевая статья о том, что такое DITA и зачем нам это нужно. Это была первая волна DITA (по крайней мере, в то время она докатилась до нас 🙂 ). А теперь говорят о новой, второй волне DITA. Давайте посмотрим, что она собой представляет.
У вас есть DITA. Что теперь?
Распространение DITA усиливается, и всё больше компаний задают этот вопрос. Для многих наших клиентов первая волна DITA означала решение вопроса о том, хорошо ли подходит этот стандарт для их контента. Компании, которые выбрали внедрение DITA, обнаружили, что повысилась общая эффективность производства контента благодаря усовершенствованному повторному использованию, автоматическому форматированию и так далее. Читать дальше…
Построение контент-стратегии для интернета вещей
16.07.2015
Интернет вещей и контент-стратегия. Бен Бароне-Нюгент — ведущий контент-стратег R/GA New York (в Твиттере: @benbn) — даёт своё видение связи этих понятий и рассказывает, на что в их контексте нужно обратить первоочередное внимание в нашем меняющемся технологичном мире.
В связном мире маркетологи должны использовать контент для того, чтобы давать людям сильные впечатления, а не просто рекламные сообщения.
Прим. пер.: как известно, одно из основных свойств Интернета — связность. Это означает, что все разрозненные интернет-узлы связаны между собой. Понятие связности происходит из теории графов. Связный граф — это граф, между любой парой вершин которого существует как минимум один путь. Интернет вещей развивает идею связности на все устройства разных классов, подключенных к Интернету. И в связи с этим имеет смысл уже говорить о связном мире как о связности высшего порядка. Читать дальше…
Что такое структурированное писательство?
18.06.2015
Статья входит в цикл «Понимание и применение структурированного писательства».
От редактора: Марк Бейкер начинает свою постоянную серию публикаций по структурированному писательству с создания рабочего определения. В дальнейшем читайте статьи о ключевых концепциях структурированного писательства и их практическом применении.
Я не любитель широких определений больших терминов. Определения должны прояснять значение, но попытки определить такие термины как «контент» и «контент-стратегия» лишь вызывают споры. Предлагаемые определения часто рассчитаны не столько на то, чтобы прояснить значение, как на то, чтобы застолбить некоторую область. Так же и сочетанию «структурированное писательство», по сути, требуется что-то вроде определения, не потому что его значения размыты, а потому что они сильно разнятся. Это результат разнородности интересов, а не отсутствия определения. Моё определение — это декларация моих интересов, не более.
Давайте начнём с как можно более общего определения типа «обхвати-руками-всё-сразу»:
Структурированное писательство — это акт создания контента, удовлетворяющего одному или более ограничениям.
9 факторов, влияющих на качество контента
10.06.2015
Понятие качества – вещь сложная, а когда дело касается контента, то, как и при оценке любого неосязаемого явления, вообще затруднительно найти подход. Что оценивать? Стиль? Так это необъективное понятие. Подачу материала? Встаёт вопрос: а как? Какой контент имеет больший вес – инструкция к продукту или маркетинговые материалы? А надо ли вообще об этом задумываться? Много вопросов, и непонятно, с какой стороны подойти. Джилл Парман, владелец компании ForWord Consulting, утверждает, что создание и поддержка качественного контента – это вызов, и она знает, как его принять. Давайте вместе с ней разберёмся, какие критерии являются решающими при оценке качества и что с ними делать, чтобы добиться результата.
Встаньте на путь к хорошему контенту, оценив качество по показателям
Посмотрите в нескольких словарях определение слова «качество» и вы обнаружите много вариантов. Поговорите с людьми, которые управляют организациями, руководят командами по обеспечению качества или ведут блог о моде или еде, и у вас появится ещё больше определений. Одно из базовых определений описывает качество так: «в какой степени что-то хорошо или плохо». Другое продвигается на шаг вперёд и предполагает, что именно указывает на качество: «высокий уровень полезности и мастерства» (оба взяты отсюда: http://www.merriam-webster.com/dictionary/quality). Значит, определить, что представляет собой качественная документация, учебные материалы или вебсайты, раз уж вы взаимодействуете с этими материалами – легко, верно? Ну, да вы уже знаете ответ на этот вопрос. Читать дальше…
3 основные ошибки управления контентом в компаниях
21.05.2015
Бывает, что в компании есть огромное количество контента. Например, вы производите множество программных продуктов, каждый из которых обновляется, имеет разные версии (положим, для стационарных ПК и мобильных устройств), к каждому продукту есть руководство пользователя, к некоторым – руководство администратора, руководство системного программиста, а также море маркетинговых материалов и т.д. и т.п. Причём каждый из документов в нескольких форматах – для веб-справки, для публикации на сайте, для печати, для просмотра на экране… Как справиться со всей этой горой контента и выстроить работу максимально эффективно, советует Джекки Сэмюэлс.
Люди тратят сумасшедшее количество времени на попытки создать, найти, распространить, обновить и ещё что-либо сделать со своим контентом. Ковыряются в электронной почте, ищут в папках, лазят по ресурсам локальной сети… Быстро ли вы находите информацию? Ту ли информацию ищете, которая вам нужна? Уверены ли, что она актуальна и не содержит ошибок? Если она больше не соответствует действительности, вы узнаете об этом? Читать дальше…
Публикация документации онлайн – 18 миллиардов причин начать
30.04.2015
Каждый разработчик хочет, чтобы потенциальные клиенты находили его продукт в Интернете. Очевидный факт – чтобы сайт находился поисковиками, на нём должна быть соответствующая информация, и чем больше – тем лучше. Думаете, это затратно? Есть один способ, который потребует от вас минимум усилий и расходов, но даст массу такой необходимой для продвижения вашего продукта информации. О нём рассказывает производитель систем для создания справочных порталов ClickHelp.
Так много причин – слишком много, чтобы составить список… И вам интересно, откуда взялась такая огромная цифра. Давайте выясним это вместе. Читать дальше…