Всем привет! Меня зовут Антон, я 9 лет занимаюсь документацией для программистов и год работаю техническим писателем в IT-департаменте Банка РНКБ. За это время у меня сложилось своё видение «хорошей» документации и методики её разработки, и я решил поделиться им с вами.

Планирую рассказать всё в двух статьях. Сегодня поговорим о документации для IT-департамента — той, которую распространяют в электронном виде, размещают на отдельном сайте и которой пользуются программисты, тестировщики, аналитики и руководители отделов. Помимо своего опыта, покажу примеры, статьи и исследования на тему ведения документации, которые помогли мне — и могут пригодиться вам.

Критерии хорошей документации

Начну с того, что лично для меня является «хорошей» документацией за годы работы и знакомства с публикациями коллег (например, такими, как эта) по теме я выработал несколько критериев оценки документации. Это не «сборная солянка» — скорее обобщённая шкала измерения качества документации в целом для проекта. Чек-лист — где-то он пересекается с методикой разработки, инструментами и т. д., но без него у меня не выйдет передать суть.

Хорошая документация должна быть:

• с чёткой структурой;

• краткой и понятной;

• достоверной;

• с поиском и навигацией;

• с правильными заголовками;

• написанной по шаблонам, с использованием стайлгайдов;

• протестированной в критических ситуациях.

Структура документации, оглавление

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

• Пользователям удобнее искать что-то в документации;

• Руководству проще оценивать объём работ;

• Техническим писателям легче выбрать место для публикации новых статей.

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

Даже если вы пришли в команду, а оглавление там уже было, не бойтесь его изменить, если видите, что можно что-то улучшить. Например, мы в РНКБ постоянно перерабатываем оглавление, потому что к нам всё время попадает что-нибудь новое для сопровождения и объём документации растёт.

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

С оглавлением разобрались, теперь поговорим о разделах. Продумайте категории для статей. Например, я подсмотрел логичное деление по категориям у коллег из Timeweb Cloud вот здесь. Вкратце: можно выделить 4 вида документации, распределённых по осям «практика — теория» и «обучение — работа». Каждая категория подходит конкретной аудитории с определённым уровнем подготовки. Ну а определившись с категориями, на их основе можно уже построить и оглавление.

Ещё полезно добавить разделы такого рода:

• Быстрый старт;

• Установка;

• Словарь терминов;

• Лучшие практики;

• Вопросы-ответы.

Обойтись без них можно, но, как показывает мой опыт, они покрывают большую часть потребностей команд. Мы в РНКБ используем эти разделы и даже создали типовые шаблоны для большинства (но о них я расскажу позже).

Появление категорий зависит и от инструмента, который вы используете. Простой пример: в РНКБ до недавнего времени документы хранили в виде отдельных файлов, так что словарь терминов к каждой статье нужно было вести прямо внутри неё. А вот когда мы перешли на Confluence, то с помощью плагина Smart Terms for Confluence — Glossary смогли ввести единый источник терминов и избавиться от их дублирования по отдельным статьям. Кстати, раз уж зашла речь о терминах, не могу не порекомендовать хорошую статью — «Говорим на одном языке. Как создать словарь терминов: 10 шагов». Она может пригодиться, если вы собираетесь создавать собственный глоссарий в проекте.

Краткая и понятная документация

Написать ёмкую документацию непросто: на это, бывает, уходит 80% времени, а первый сырой вариант текста часто оказывается громоздким. Пугаться не стоит: путём поиска вариантов со временем вы сможете его улучшить по мере сил. Главное же, о чём вы должны помнить при написании документации, — у ваших коллег будет мало времени на её чтение. Им нужно быстро найти готовое решение задачи и вернуться к своим делам, а не копаться в текстах (и коллеги из Plesk говорят о том же).

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

Старайтесь снизить порог вхождения для потребителей документации. Чем она будет проще и понятнее для них, тем лучше. Пишите в разговорном стиле: такой текст легче воспринимать. Объясняйте простым языком, приводите аналогии, метафоры — используйте все средства, чтобы доступно донести информацию. Добавляйте дополнительные материалы, если они у вас есть. Это могут быть:

• перекрёстные ссылки на поясняющую документацию;

• картинки и схемы;

• демопримеры.

Чтобы было нагляднее, назову несколько примеров документации, на которые я сам ориентируюсь: Vue.js, JS API из Яндекс.Карты, справочники о Python издательства O’Reilly («Простой Python» и т. д.). Вы в процессе работы можете сформировать свой топ и равняться на него.

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

1. В одной из публикаций на Habr наткнулся на ряд исследований (например, здесь и здесь), касающихся восприятия сути текста, а также поиска в нём отдельных слов, в зависимости от количества символов в строке. Если коротко, то людям обычно нравятся тексты со строками в 55–70 символов. В таких текстах читатели лучше понимают смысл и легче отвечают на вопросы, да и читают их быстрее. Зато в текстах с длиной строки в 85–100 символов люди быстрее находят конкретное слово.

2. Здесь упоминается проведённое Neilson Norman Group исследование направления взгляда. Полезные для нас выводы отсюда: пользователи читают страницы по F-шаблону, поэтому на них должны быть заголовки, абзацы, маркированные списки, а длина строки — до 90 символов. Так что лучше делать небольшие статьи, которые решают конкретные задачи, и важную информацию по теме нужно разместить в первых трёх предложениях на странице.

Достоверность

У потребителей должен быть единственный актуальный источник документации. Мы в РНКБ пишем документацию в Confluence, и кроме технических писателей там же ведут работу множество других отделов, включая программистов, тестировщиков, аналитиков и менеджеров проектов. При таком подходе в поиске могут появляться дубли и черновики, которые по-хорошему должны быть скрыты от пользователей. Поэтому мы в обозримом будущем планируем работы по организации единственного источника документации и когда-нибудь поделимся собственным опытом.

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

Поиск и навигация

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

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

Проверьте, настроена ли навигация по странице. Лучше сделать её в виде плавающего бокового меню. Особенно если текст статьи помещается на нескольких экранах — тогда читателю будет удобно с ним работать.

Правильные заголовки

Заголовки определяют качество поисковой выдачи, отсекают дубли статей из разных разделов и выполняют ещё множество важных функций. Поэтому их нужно тщательно продумывать — вплоть до оптимизации их длины. Где можно, пишите короче, но и не увлекайтесь: если аббревиатуры используются редко и не на слуху, лучше их избегать. Простой пример из практики РНКБ: у нас в документации есть РП и РА. Очевидно ли вам, что это «руководство пользователя» и «руководство администратора»? Следите за подобными моментами, ищите другие способы сокращать заголовки, перебирайте в уме формулировки в поисках лучшей.

Например, у вас есть:

Руководство пользователя по установке IDE PyCharm

Сделайте:

Установка IDE PyCharm

Шаблоны, стайлгайд

В РНКБ для большинства документов есть шаблоны — и это здорово упрощает жизнь и нам, техписателям, и пользователям. Коллеги из Яндекса в одном из докладов на Гипербатоне говорили о важности единого стиля в оформлении документации, и я с ними соглашусь: это улучшает пользовательский опыт документации. Проще говоря, пользователь ожидает увидеть схожую по теме документацию на том же месте, где видел её в предыдущий раз на другой странице. Так что разработка стайлгайда — это важно, и заниматься ею тоже приходится техписателям.

О чём редко упоминают

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

Важно находить уязвимые места документации, чтобы от работы с ней стресса не становилось ещё больше. Здесь ценной будет обратная связь от программистов или руководства: прислушайтесь к ним и узнаете, что ещё стоит проработать. А ещё можно синтезировать и пройти «стресс-тесты» заранее, чтобы убедиться в качестве документации. Когда-нибудь это вас спасёт.

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

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

Я разбил этот план на этапы:

• Этап 1. Описание работ и критерии сдачи:

  • Получить описание задачи.

  • Определить критерии сдачи работы.

  • Утвердить лица, которые будут:

    • консультировать по теме;

    • проверять результат;

    • принимать решение о завершении работы.

  • Включить в план работ этим лицам время для выполнения их ролей.

• Этап 2. Подготовка оглавления:

  • Разработать план статьи.

  • Проверить его с разработчиком или заказчиком.

  • Исправить замечания.

  • Утвердить.

• Этап 3. Разработка черновика:

  • Собрать первичную информацию по каждому разделу плана статьи.

  • Создать первый черновик, строго следуя плану.

  • Выполнять итерации:

    • проверить черновик с консультантом;

    • исправить замечания.

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

• Этап 4. Публикация статьи:

  • Вычитать текст (опечатки, стилистическое оформление текста и т. д.).

  • Исправить неточности.

  • Утвердить текст.

  • Опубликовать статью на сайте.

• Этап 5. Сбор обратной связи:

  • Опубликовать новость или сделать рассылку о новой статье.

  • Собрать замечания через формы комментариев и опросов о качестве статьи.

  • Доработать статью по замечаниям.

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

Кстати, об оценках. Мы в РНКБ начали рассылать новости со списком обновлений в документации только недавно. Когда мы просили оценить качество работ, вовлеченность была невысокая: оценку выставили менее 1% сотрудников. Большие коллективы инертны, так что подобная обратная связь — обычное явление. Но с этим можно работать: попытаться донести до разработчиков, что участвовать в проверке документации — в их же интересах, потому что от неё зависит и их работа.

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

Напоследок расскажу ещё немного о нашей команде техписателей в РНКБ. Каждый день мы:

• документируем новые интеграционные сервисы;

• разрабатываем руководства администратора, пользователя и т. д.;

• актуализируем и перерабатываем legacy-документацию;

• находим, тестируем и внедряем новые инструменты для разработки, оценки качества и представления документации на внутреннем портале IT-департамента;

• консультируем по документации и поиску нужного ответа (как сервисы «Вопрос-ответ», Stack Overflow).

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

Нас в команде пятеро, но мы планируем расширять штат. Так что если вы техписатель, ищете работу и вам интересны описанные выше задачи нашей команды, загляните к нам на HH.ru — возможно, мы с вами познакомимся не только как автор и читатели на Хабре. Да, если вы не техписатель — всё равно заглядывайте: у наших коллег много других вакансий.

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