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

Новости о техническом писательстве

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

17.11.2017

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


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

 

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



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

25.09.2017

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

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

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

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

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

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



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

08.12.2016

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


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

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

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

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

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

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



Отчёт о Доквариуме №2 «Видеодокументация»

29.11.2016

1233623 ноября прошёл второй Доквариум,  посвящённый теме «Видеодокументация».

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

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

А также:

  • какими инструментами пользуются сами докладчики
  • лайфхаки «из первых рук»
  • ошибки, через которые пришлось пройти нашим докладчикам, чтобы наработать мастерство
  • ответы на многие другие вопросы!

Огромное спасибо докладчикам за выступления и участникам за активность и интересные вопросы!

 

Программа:

  1. Использование формата видео для технической информации

Павел Семёнов, аналитик, АО «СберТех», г. Новосибирск

  1. Снимать или не снимать? (Обучающие видео как один из типов контента для поддержки пользователей)

Мария Большакова, руководитель отдела обмена знаниями, Марина Соболевская, руководитель группы веб-контента, Лабораторая Касперского, г. Москва

  1. Видеоинструкции: от сценария до публикации

Алексей Мартин, руководитель учебного центра Naumen Contact Center, г. Москва

  1. Ответы докладчиков на вопросы участников

 

Для всех, кто не был, мы предоставляем запись Доквариума. Будем рады, если информация окажется вам полезной! И ещё нас очень порадует, если напишите нам пару слов обратной связи – здесь в комментариях или на адрес: info@protext.su 🙂

А если вы решили начать разрабатывать видеоинструкции для вашего продукта и хотите доверить этот процесс подрядчику – обращайтесь к нам!

 



Адвокат пользователя: Балансирование между документами оперативной поддержки и опытом пользователей

29.01.2016

01Автор статьи – Нил Каплан (Neal Kaplan), главный менеджер по поддержке пользователей компании Interana в Редвуд-Сити, США. Нил имеет двадцатилетний опыт в области технических коммуникаций и обучении пользователей. Сравнивая документацию и здания, он делится своим опытом о том, как найти баланс между долговечностью и скоростью, между поверхностью и структурой, между оперативной поддержкой и опытом пользователей.


Я провёл День Благодарения у родственников в Сан-Диего. Мы посетили Парк Бальбоа, место нахождения двух международных экспозиций (1915 и 1935 гг.). Здания для этих экспозиций, хотя и тщательно детализированные, построены из мелкой проволочной сетки и штукатурки. Они должны простоять в течение года, пока выставлена эта экспозиция, и затем будут разрушены. Они красивы, но не предназначены стоять веками. Они оба были внесены в национальный реестр в качестве исторических памятников.

Всё это применимо и к большей части нашей документации (за исключением части про исторические памятники). Читать дальше…



Вышел Dr.Explain 5.2

18.12.2015

DrExplainСегодня мы расскажем об очередном обновлении российской программы для создания документации Dr.Explain и поделимся советами от директора компании-производителя Индиго Байт Дениса Журавлёва о том, как правильно организовать навигацию в онлайн-документации на сайте проекта.

Приобрести Dr.Explain Вы можете в нашем интернет-магазине. Компания «ПроТекст» является прямым партнёром компании Indigo Byte Systems.

Компания Indigo Byte Systems недавно выпустила обновление для Dr.Explain — версию 5.2. Если вы пользуетесь Dr.Explain версии 5.х, то данное обновление для вас бесплатно. Если вы ещё не установили его, то очень рекомендуем скачать новый дистриубтив с этой страницы.

Что нового в Dr.Explain 5.2

  • Адаптивный дизайн онлайн-справки позволяет пользоваться ей даже на мобильных устройствах.
  • Автонумерация разделов документации.
  • Протестированная совместимость с Windows 10.
  • Возможность импортировать большие MS Word файлы.
  • Улучшенная поддержка для RTL-языков (Right-To-Left writing).
  • Более гибкая настройка многоуровневых списков
  • Улучшено много компонентов таких, как PDF- и HTML-экспорт, текстовый редактор, импорт документов и другие функции.

Чтобы лучше понять подход, который используют разработчики Dr.Explain при разработке и позиционировании этого продукта, мы задали Денису Журавлёву, директору Indigo Byte Systems, вопрос о балансе между удобством работы технического писателя (они стремятся работать в домене носителя) и степенью контроля за структурой документов (домен документа) и получили следующий ответ: Читать дальше…



Зачем мне технический писатель?

14.10.2015

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

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


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



Когда вашей документации требуются скриншоты?

30.09.2015

01Скриншотам – быть или не быть? Существуют ситуации, когда скриншоты необходимы, но в основном они только мешают. Какой потенциальный вред от скриншотов бывает и как определиться с их количеством – читайте в статье.


Один из частых вопросов при разработке документации: «Сколько скриншотов она должна включать?» Ответы разнятся от «Ни одного!» до «Все окна!». Картинка может заменить тысячи слов, но скриншоты часто используются в качестве «костыля» для некачественной документации или некачественного дизайна. Лучший ответ — использовать их там, где необходимо, и не использовать в других случаях. Но как узнать, когда они необходимы? Читать дальше…



Публикация документации онлайн – 18 миллиардов причин начать

30.04.2015

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

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

Так много причин – слишком много, чтобы составить список… И вам интересно, откуда взялась такая огромная цифра. Давайте выясним это вместе. Читать дальше…



Советы и хитрости: Создание видеозаписей для обмена в Интернете (часть 2)

26.09.2014

26.09.14Продолжаем публикацию советов Бернарда Ашвандена по созданию видеороликов. Он максимально просто и доступно описал процесс подготовки и записи небольшого ролика. После такой тренировки и крупные проекты не вызовут проблем.

Ищите, где заказать разработку обучающих видеороликов? Специалисты компании «ПроТекст» справятся с этим на отлично! Подробнее на этой странице.

Начало данной статьи читайте тут: Советы и хитрости: Создание видеозаписей для обмена в Интернете (часть 1)


Совет 3: Запишите видео (но молчите при этом)

Я делаю запись, следуя инструкциям. Скорость не имеет никакого значения, я могу настроить её позже. Конечно, если вы делаете полнометражную (full-motion) запись, то правильно планируйте время. Мне нравится записывать «слайдами», которые я могу затем настроить. Так в чём тут совет? Только в том, что вам надо сосредоточиться на записи. Не пытайтесь делать ещё 10 других вещей одновременно. Например, добавлять аудио или эффекты, или что-нибудь еще. Читать дальше…