Дао разработки справочной документации для IT-продукта

Привет!

Любите читать хелпы? А писать? Думаю, что 99% из вас ответят “НЕТ”.

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

В этой статье я бы хотел поделиться нашим опытом и описать процесс создания справочной документации, который мы используем в Alconost Help…

Роли

Для начала давайте определимся с типовыми ролями в проекте. Обычно к созданию справки причастны:

• Разработчик (программист или продакт менеджер);
• Технический писатель;
• Менеджер проекта.

Сюда можно добавить еще редактора, переводчиков и дизайнера.

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

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

Сами vs. аутсорс

Если у вас большая компания, много продуктов и есть чем загрузить технического писателя на 100%, оптимально будет найти или вырастить технического писателя. Следует учесть, что технический писатель — это достаточно редкая профессия; эти люди всегда имеют много хорошей работы и редко ее ищут, т.е. отделу кадров придется поднапрячься.

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

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

Отдавать разработку справки на аутсорсинг полезно еще по одной причине. Внешние технические писатели могут найти баги, посоветовать разработчику некоторые улучшения в интерфейсе или предложить собственные идеи по развитию программы. Этот пристальный (а технический писатель изучает программу глубже обычного пользователя) “взгляд со стороны” никогда не окажется лишним. Разработку справочной документации может считать дополнительной стадией QA.

Требования к результату

Итак, ближе к делу.

Не важно, своими силами или силами аутсорсера вы будете делать справку, на первом этапе вам потребуется четкое представление о том, что собственно нужно. Справка бывает разная, я писал об этом в прошлой статье Виды и форматы справок (инфографика) — выберите, что вы хотите в качестве конечного результата.

Процесс

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

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

1. Бриф

Даже если вы собираетесь писать справку самостоятельно, сперва будет неплохо ответить себе на ряд важных вопросов о продукте. А если справку вы заказываете на стороне — будет странно, если вам эти вопросы не зададут.

Этот документ (бриф) послужит своего рода ТЗ для технического писателя. В процессе заполнения вы точно определяетесь с требованиями к формату справки, примерным объёмом текста, целевой аудиторией, языками, уровнем подготовленности пользователя и т.д.

2. Содержание

Правильно составленное содержание — это половина дела. Если материал справки хорошо структурирован, ваши пользователи найдут нужную информацию за пару кликов. Не спешите сразу же писать текст, лучше детально проработайте иерархию и уровни вложенности топиков.

Для работы со структурой справки можно использовать простой spreadsheet. По ходу составления содержания вы сможете определиться с обязательными для упоминания моментами, ключевыми словами (онлайн-хелп на сайте послужит и для SEO), количеством и содержанием скриншотов, приблизительным объёмом текста. На этом этапе можно оценить сроки и бюджет проекта.

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

3. Оформление хелпа

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

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

4. Контроль промежуточных версий

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

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

5. Финальная версия

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

Прочтите получившийся хелп целиком и внесите последние правки.

6. Вычитка (пруфридинг)

Я рекомендую отдавать текст справки на вычитку профессиональному редактору. Грамотный текст и отсутствие опечаток и ошибок повышают доверие пользователей к компании и авторитет разработчика.

7. Экспорт документации

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

Инфраструктура

Для хранения проектов справки, иллюстраций и исходных данных я рекомендую использовать облачные хранилища данных с возможностью многопользовательской работы и контролем версий (dropbox, box.com), а так же онлайн-документы (googe docs, office360).

В качестве хранилища данных подойдёт Box.com. Плюсы:

• синхронизация с локальными файлами
• система уведомлений
• комментарии к файлам
• история версий
• права доступа

Для брифов, таблиц со структурой хелпа удобно использовать Google docs. Плюсы:

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

Финал

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

А пока жду от вас комментариев, предложений и вопросов. Как справочную документацию пишете вы?