Стратегии написания эффективной технической документации

Я занимаюсь техническим писанием того или иного рода с 1999 года, когда занимался контролем качества в научно-исследовательском отделении Altec Lansing в Кфар-Сабе, Израиль. В то время мы выпускали инновационные аудиоустройства, такие как (вздох) USB-аудиоустройства, которые работали на Windows ME и 2000. Они содержали ошибки, и их настройка была не такой простой задачей, как сегодня.

Нам нужны были документы.

У нас были некоторые препятствия, которые пользователям приходилось преодолевать, и нам нужен был способ документировать, в чем они заключаются, каковы были крайние случаи, а также как диагностировать и исправлять все эти проблемы. Он должен был быть красиво упакован, четко отформатирован и доступен пользователям, установившим наше вспомогательное приложение. Я нашел приложение Robohelp, которое используется для создания стандартных справочных приложений в Windows, и добавил файл справки в нашу установку.

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

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

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

Основная концепция документации

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

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

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

• Документы должны быть доступны для поиска , потому что, если серьезно: это несложно. Если в ваших документах нелегко найти что-то, ваши пользователи не найдут то, что им нужно.

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

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

  
  

Целостные документы — это хорошо продуманные продукты

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

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

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

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

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

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

Делаем хорошие документы

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

Вам нужно:

• Знайте, почему вы создаете свои документы
• Знайте, кто ваша целевая аудитория
• Знайте, каковы их болевые точки
• Улучшайте свои документы с течением времени

Давайте подробнее рассмотрим каждый из них.

Знание причин ваших документов часто представляет собой действительно простой вопрос и ответ, лежащий на поверхности. Вы создаете документацию, потому что, если вы этого не сделаете, пользователи останутся незамеченными и не смогут использовать ваш продукт. На более глубоком уровне есть конкретный ответ для вашего варианта использования. У вас есть инструмент разработчика? Это один набор ответов. У вас есть инструмент для дизайна розничной торговли? У вас есть SaaS-продукт для бухгалтерского учета? У вас есть автоматическая кофеварка? Это все отдельные наборы ответов.

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

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

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

Ваши документы — неотъемлемая часть вашего успеха

Я подведу итог, просто подчеркну, насколько критически важны документы. Без них ваши пользователи будут предоставлены сами себе и им придется постоять за себя.

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

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