Всё для технического документирования
+7 (495) 001-40-42
Разработка технической документации
Курсы для технических писателей
Программное обеспечение

Публикации

Минимизируем документацию

17.11.2017

О том, как минимизировать количество документации и почему это важно, рассказывает Том Джонсон. И хоть эта статья довольно старая (ей 8 лет), тренды, которые наметились в то время, подтвердились и актуальны по сей день. А значит, применимы и советы, данные в этом материале.


На одной из конференций по дизайну интерфейса докладчик Грант Скоусен показал такой рисунок:

 

Простота и сложность Читать дальше…



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

25.09.2017

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

Нет времени писать и/или тестировать инструкции? Заказать разработку инструкции в компании «ПроТекст» — лучшее решение!

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

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

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

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



21 совет по веб-дизайну для начинающих

28.07.2015

01Мы продолжаем мини-серию статей, посвящённую дизайну, темой веб-дизайна. Здесь речь идёт не только о внешнем виде сайта, но и о текстах, удобстве и авторских правах. Кто знает, чем придётся заниматься вам, как техническому писателю, завтра? А может быть, следить за веб-сайтом компании уже входит в ваши обязанности или у вас есть свой сайт, как у небезызвестного Тома Джонсона? Тогда сегодняшний материал – для вас.

Предыдущая статья серии: Советы по графическому дизайну для начинающих.

 

Каждый хочет стать успешным профессиональным веб-дизайнером, но немногие становятся.

Что они делают для того, чтобы стать успешными?

Здесь нет секрета. Есть лишь постоянное безостановочное обучение. Есть шанс, что вы потерпите одну, две, три неудачи, но вы не должны останавливаться. Встреча с трудностями, преодоление различных проблем и создание множества вещей, относящихся к веб-дизайну, сделают из вас успешного веб-дизайнера. Читать дальше…



Единый источник и дублированный контент (поисковая оптимизация) (Часть 2)

28.11.2014

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


Переход от печатных к веб-моделям

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

Я думаю, одержимость технических коммуникаторов единым источником и повторным использованием – признак того, что они застряли в «бумажном» мышлении. Повторное использование имеет смысл в бумажном мире, потому что человек, читающий одну книгу, должен приложить массу усилий, чтобы обратиться к другой книге – в некоторых случаях это может быть несколько дней или недель усилий и значительных расходов. Лучше тогда повторять материал в каждой книге, где он может потребоваться, чем ссылаться на другую книгу, которую читателю будет трудно искать. Читать дальше…



Единый источник и дублированный контент (поисковая оптимизация) (Часть 1)

26.11.2014

26.11.14Если вы сумели решить проблему с написанием качественного контента, перед вами тут же встаёт новая и не менее важная: контент, к которому не могут получить доступ пользователи, ­– это впустую потраченные деньги и время. Сегодня с помощью Тома Джонсона мы попробуем понять некоторые поисковые механизмы Google и обернуть их в свою пользу.


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

Под единым источником здесь я подразумеваю несколько интернет-версий контента, не обязательно версии для различных сред. Предположим, у вас есть 9 онлайн руководств для «ACME Software»: версия 1.0, версия 2.0, версия 3.0. И для каждой версии у вас есть руководство для начинающих, руководство администратора и гайд по должностным обязанностям (для руководства). Кроме того, у вас есть печатные версии каждого из 9 руководств. Это означает, что в общей сложности их у вас 18. Читать дальше…



Две истории о том, как писать справку (часть 2)

15.08.2014

15.08.14Продолжаем рассказ о разных подходах к написанию справки к софту. Том Джонсон, технический писатель из Калифорнии, наглядно на примере показывает нам результаты таких разных подходов. Первая часть статьи тут.


История № 2

Проектная команда компании «Рога и копыта» создаёт комплексное приложение для большого числа пользователей и решает привлечь техписа для написания справочных материалов для пользователей. Техпис создаёт максимально полную справку, основываясь на исследованиях проектной команды, пользователей, тестовых требований и других спецификаций.

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



Две истории о том, как писать справку (часть 1)

13.08.2014

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


То, как большинство техписов подходят к написанию справки, в корне неправильно. Прочитайте эти две истории о разных подходах и мышлении разных писателей.

История № 1

Проектная команда компании «Рога и копыта» создаёт комплексное приложение для большого числа пользователей и решает привлечь техписа для написания справочных материалов по использованию приложения. Техпис месяцами работает бок о бок с разработчиками при создании приложения. За это время он тщательно собирает информацию и пишет топики справки, основываясь на задачах. Читать дальше…



Писательские навыки против технических, или что я понял, решая судоку (часть 2)

30.04.2014

30.04.14Думаем, предыдущая статья заинтриговала наших читателей. Казалось бы, как связаны судоку и карьера технического писателя? Но Тома Джонсона эта несложная головоломка навела на интересные мысли. Начало истории тут.


Утром я показал дочери, как решать головоломку. Стратегия поставила её в тупик.

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

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

Также мне нравится представлять, как части работают вместе, отдельно от кода. Я часто устраиваю безжалостное тестирование методом проб и ошибок, чтобы понять, как всё работает. Как только я разобрался, я тут же пишу описание с объяснением и перехожу к следующей проблеме. Читать дальше…



Писательские навыки против технических, или что я понял, решая судоку (часть 1)

28.04.2014

01Мы часто задаёмся вопросом, должен ли технический писатель быть в первую очередь технарём или писателем. Может ли языковед стать техписом, и достаточно ли инженерных знаний, чтобы написать руководство пользователя. Том Джонсон, технический писатель из Калифорнии, попытался ответить.


Недавно мне пришёл вопрос от читателя:

У меня две специализации в английском, я преподаю в университете штата Пенсильвания. Я пытаюсь выяснить, сколько технических навыков мне придётся приобрести, чтобы стать техническим писателем. Где-то я прочитал, что технический писатель на 90% технарь и на 10% писатель. Как вы думаете, насколько глубокие технические знания нужно иметь?

Позвольте мне ответить, основываясь на недавнем опыте. На днях моя дочка-третьеклассница принесла домой пазл Судоку 6?6 в качестве домашнего задания и озадачилась его решением. Я никогда не пробовал свои силы в судоку, да и вообще никогда не интересовался подобными головоломками. Я сказал ей, что её мама, вероятно, справится лучше, но дочка объяснила, что мама уже пыталась. Мама (Шеннон) заметила из другой комнаты, что её «мозг не заточен под судоку». Это меня заинтриговало, так что я сел и попытался решить головоломку. Читать дальше…



Что делать со старыми инструкциями? (часть 2)

13.12.2013

01Представляем вам продолжение письма Тома Джонсона, опубликованного в его блоге. Первая часть тут.


Чтение всех этих руководств неизменно начинается с поздравлений с покупкой продукта. Я уже писал об этих клише в статье Five Ways to Avoid the “Congratulations Clich?. Но теперь я вижу в таких приветствиях реальную цель. Всё, что хочет сказать технический писатель, – это «спасибо, что приобрели этот продукт, без вашей поддержки я остался бы без работы». Это код, который понятен только братству техписов. Как видите, у меня есть доступ к подобным тайнам. «Спасибо, спасибо, что наняли меня» – говорят они.

Я бы хотел, чтобы люди, которые создают инструкции по сборке устройств, добавляли в свои руководства немного юмора, чтобы немножко улучшить моё плохое отношение к сборке чего-либо вообще. Однажды я собирал пару двухъярусных кроватей из IKEA, а к ним шёл такой огромный пакет с гайками, что, клянусь, их туда насыпали лопатами.

Ненавязчивая шутка в начале руководства может неплохо помочь. Как насчёт «Пожалуйста, возьмите и взвесьте в руке здоровенный мешок гаек. Вашей первой мыслью будет: «Боже, сколько гаек!». Мы знаем, знаем, успокойтесь. Через пару часов всё закончится. Ну, если, конечно, вы отлично умеете работать руками. Шучу, наша инструкция вам поможет. Но на самом деле, не теряйте гайки. Вам понадобится все до единой 🙂 ».

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