Как составить документацию к приложению

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

Осенью 2016 года нам с коллегой поручили улучшить документацию и контент в моей бывшей компании. Мы потратили год на все виды документации: справочник по API, руководства, учебные пособия, сообщения в блогах. До этого я 5 лет писала доки, но официально не обучалась этому. Но и неопытной меня нельзя назвать: кроме документирования API для проектов и стартапа, я ещё преподавала Python Flask на семинарах во время учёбы на последних курсах в университете. Но сейчас выпала возможность сосредоточиться только на любимом деле: помогать специалистам всех уровней через техническую документацию.

В этом году я многому научилась в сообществе Write The Docs, у других провайдеров API, а также методом проб и ошибок. В прошлом году я поделилась опытом в докладе «Что мне хотелось бы знать о написании документации» на конференции API Strategy and Practice в Портленде. Эта статья — обзор полученных знаний.

Как люди на самом деле читают документацию?

«Нация содрогается от большого фрагмента слитного текста», фото The Onion

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

В исследовании направления взгляда Neilson Norman Group в 2006 году 232 пользователя просмотрели тысячи веб-страниц. Оказалось, что пользователи обычно смотрят на страницы по F-шаблону:

1. «Сначала читают в горизонтальном направлении, как правило, в верхней части области с контентом. Это верхний элемент фигуры F».
2. «Затем немного перемещаются вниз по странице — и совершают второе горизонтальное движение, которое обычно охватывает более короткую область, чем предыдущее. Этот дополнительный элемент образует средний элемент фигуры F».
3. «Наконец, пользователи сканируют левую сторону контента по вертикали. Иногда это медленное и систематическое сканирование, которое отображается в виде сплошной полосы на теплокарте. Иногда движение более быстрое, образующее пятна на теплокарте. Это последний вертикальный элемент в фигуре F».

Теплокарты Nielsen Norman Group

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

Важно отметить, что F-шаблон мешает пользователям, но хорошее позиционирование контента помогает предотвратить F-сканирование.

Каковы конкретные последствия для документации?

• В первых двух абзацах следует указать самую важную информацию
• Критически важны первые 3−5 слов
• Заголовки, абзацы и маркированные списки с информативными словами
• Изменения шрифта (размер, ссылки, выделения жирным и т. д.) могут быть необходимы, чтобы удержать внимание читателя

Так как структурировать контент на странице?

• Предотвратите сканирование: убедитесь в выделении информации, которая нужна читателю
• Одна мысль на абзац. Если их несколько, разбейте абзац
• Пользователи пропускают всё, что похоже на баннеры, поэтому будьте осторожны с иллюстрациями
• Не расширяйте слишком сильно колонку с текстом: оптимально 65−90 символов

Некоторые из этих советов я узнала из лекции Кевина Берка «Как писать документацию для пользователей, которые её не читают». Кевин поддерживал документацию Twilio с 2011 по 2014 годы.

Кроме того, у абзацев есть своя специфика. Подобно слитному тексту The Onion, когда вы читаете много абзацев, можно пропустить суть. Тогда зачем использовать их так часто? Давайте проведём эксперимент из документации Keen IO:

Быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил: в названии должно быть не более 64 знаков. Оно должно содержать только символы ASCII. Оно не может быть значением null.

Теперь быстро прочитайте это:

У наборов событий может быть практически любое название, но есть несколько правил:

• В названии должно быть не более 64 знаков
• Оно должно содержать только символы ASCII
• Оно не может быть значением null

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

Позже мы подробнее обсудим вёрстку документации и навигацию по ней.

Примеры кода

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

Контекст в примере кода важен для успеха разработчика. Разработчики любят быстро копировать и вставлять. Вот пример с Keen IO API:

var client = new Keen({
  projectId: "your_project_id",
  writeKey: "your_write_key"
});

var ticketPurchase = {
  price: 50.00,
  user: {
    id: "020939382",
    age: 28
  },
  artist: {
    id: "19039",
    name: "Tycho"
  }
}

client.addEvent("ticket_purchases", ticketPurchase);

Разработчик быстро копирует и вставляет этот код. И…

Во-первых, как они вообще запускают файл? Вероятно, как node file_name.js, но этого нет в коде. Можно было бы указать в комментарии вверху.

Хорошо, они запустили его и… ReferenceError: Keen is not defined. 🙁 Клиент Keen не инициировался, в верхней части нет оператора import или require, и он работает только после установки библиотеки npm.

Пользователь всё починил и запустил ещё раз… Угадайте?! Ещё одна ошибка! your_project_id и your_write_key отсутствуют.

Всё это можно было бы сделать более очевидным.

Вот пример из документации Twilio, которая предоставляет хороший контекст для конечного пользователя:

Скриншот из документации библиотеки Twilio Node Helper

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

Копипаст багов

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

# Скопируйте и вставьте следующую команду
$ gem install rails

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

bash: command not found: $

Распространённая ошибка. Либо вы хотите, чтобы команда выглядела как в командной строке, либо вы случайно её скопируете. Я бы рекомендовала отказаться от $. Ещё можно найти способ запретить копипаст этого символа, чтобы ошибка не раздражала пользователей.

Более свежий пример: вы проверяли, насколько легко выделить код, который пользователь хочет скопировать?

Келси Хайтауэр изо всех сил пытался скопировать образец кода из StackOverflow на презентации Google Cloud Next.

«Хорошие программисты копируют, великие программисты вставляют»

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

«Вот и всё!»

«Вот и всё!» Фраза кажется довольно безобидной вне контекста, но представьте, как воспринимаются определённые слова вроде «легко», «просто», «тривиально» и «несложно», когда у вас проблемы — не здорово! Когда человек застрял, пытаясь заставить API работать, такая фраза подвергает сомнению его интеллект и заставляет задать вопрос: «Значит, я глупый?» Это деморализует.

Чрезмерное упрощение

Упрощение встречается повсеместно. Оно наиболее распространено среди новичков в написании документации. Зачастую авторы документации — одновременно и разработчики системы, поэтому некоторые вещи им кажутся «лёгкими». Но ведь они разработали эту функцию, написали для неё код, проверили много, много раз, а потом написали документацию. Когда вы делаете что-то десятки раз, то ясное дело, что это будет «легко» для вас. Но как насчёт того, кто никогда раньше не видел UI или функцию?

Сопереживание

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

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

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

Сообщения об ошибках как вид документации

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

Кейт на сайте Write The Docs рассказывает много полезного о написании сообщений об ошибках. Многое я узнала во время прошлой работы над сообщениями об ошибках API, а также будучи на другой стороне баррикад, получая сообщения об ошибках других API в качестве разработчика.

Кейт говорит, что хорошие сообщения об ошибках построены на трёх принципах:

• Скромность
• Гуманность
• Полезность

Скромность

Сразу нужно извиниться, даже если это не ваша вина. Это я практикую также в службе поддержки.

Пример:

Извините, не удалось подключиться к ___. Пожалуйста, проверьте сетевые настройки, подключитесь к доступной сети и повторите попытку.

Гуманность

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

Пример (ошибка кода состояния 401 у Twilio):

{ 
    “code”: 20003,
    “detail”: “Your AccountSid or AuthToken was incorrect.”,
    “message”: “Authenticate”,
    “more_info”: “https://www.twilio.com/docs/errors/20003",
    “status”: 401
}

Полезность

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

Пример:

Извините, изображение, которое вы пытались загрузить, слишком большое. Попробуйте снова с изображения меньше, чем 4000px по высоте и 4000px по ширине.

Как писать сообщения об ошибках

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

Плохой пример:

Нажмите кнопку «назад», чтобы вернуться на предыдущую страницу.

Хороший пример:

Чтобы вернуться на предыдущую страницу, используйте кнопку «назад».

Сообщения об ошибках в документации

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

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

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

Источник: https://www.twilio.com/docs/api/errors

Stripe делает нечто подобное с детальным описанием различных кодов ошибок.

Источник: https://www.twilio.com/docs/api/errors

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

Подсказка: если кто-то не ответил скромно, по-человечески и с пользой, то с достаточной «репутацией» можно редактировать ответы StackOverflow.

Выбор слов

У многих слов есть устоявшиеся ментальные модели. Например, такие слова, как «библиотеки», SDK, «обёртки» и «клиенты» уже перегружены и проходят мимо внимания читателя.

В своей лекции «Даже для этой лекции трудно подобрать название» на Write The Docs Рути Бендор говорит, почему выбор правильных слов может быть таким трудным.

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

В такой ситуации как никогда справедлива известная поговорка: «Есть только две трудные задачи в области информатики: инвалидация кеша и придумывание названий». Цитату часто приписывают Филу Карлтону, но сегодня ходит много вариантов этой поговорки. Иногда в конце добавляют «… и ошибка на единицу». Рути считает это демонстрацией, что программное обеспечение в наши дни во многом основано на чужом коде или работе.

Почему же сохраняются плохие названия объектов (или документация)?

Как и с чрезмерным упрощением, мы часто не понимаем, что название плохое. Это то, что Рути называет сбоем эмпатии. Это как сказать, что проблема неудачных слов меня не касается, поэтому её не существует.

Подсказка для США: во избежание случайного расизма используйте слова «запрещённый список» и «разрешённый список» вместо «чёрный» и «белый».
(Источники: Андре Штальц и rails/rails/issues/33677)

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

Наконец, Рути упоминает ошибку локализации. Например, слово Bing по-китайски означает «больной».

Согласно исследованию GitHub Open Source Survey за 2017 год:

Почти 25% разработчиков читают и пишут по-английски не «очень хорошо». При общении в проекте используйте понятный и доступный язык для людей из неанглоязычных стран.

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

Подсказка: я твёрдо верю, что один из величайших «трюков» для решения этих проблем — разнообразие команды, работающей над документацией.

Есть ещё случаи, когда мы признаём ошибку, но не можем или не хотим её исправлять, потому что мы…

• Привязаны к ней
• Не находим времени
• Не видим важности
• У нас нет агентства, чтобы её исправить

Вы можете сказать или услышать: «Но это моё детище!», «Кто убрал мою конфетку?» «Если мы переименуем, всё сломается», «Не верю, что изменение этого названия повлияет на что-то важное».

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

Как правильно подобрать слова?

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

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

• смутить
• огорчить
• ввести в заблуждение
• запутать
• оскорбить

С другой стороны, хорошие названия:

• способствуют внезапному прояснению («вот оно что!»)
• вводят в контекст
• объясняют
• освещают
• оказывают поддержку

Рекомендую учитывать эти качества при вычитке документации, чтобы составить полезные и честные отзывы о ней.

Подбирать верные слова трудно. Волшебной формулы не существует. Все пользователи отличаются, как и варианты использования продукта; что работает для одних, может не работать для других. Если бы это было легко, у всех была бы намного лучшая документация. Как говорит Рути разработчикам: «Написание программ — это упражнение в придумывании названий. Смиритесь с этим». И если вы пишете документацию для чужой программы, «сообщите разработчику, если его названия не попадают в цель».

Составляем документацию разработчика пошагово без диет и тренировок

Недостаточно просто написать инструкции — важно, как, в каком порядке и где вы их разместите. 

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

• инфраструктурой as a service;

• фреймворками и библиотеками на Go, C#, TypeScript;

• трейсингом, мониторингом, логированием, нагрузочным тестированием;

• инструментами для работы с базами данных и аналитикой;

• виртуализацией и контейнеризацией.

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

Дисклеймер: в этой статье упор сделан на содержание, структуру и формат. Сугубо гуманитарные вещи вроде орфографии и пунктуации обсуждать не будем — они на вашей совести.

Зачем вам документация

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

Плюсы хорошей документации:

• увеличивается bus-фактор: знание распространяется между большим числом людей, и его сложнее потерять;

• команда не отвлекается на ответы на одни и те же вопросы и занимается своей работой;

• коллеги быстро находят ответы (в том числе через Ctrl+F), решают проблемы и разбираются в технологии: как следствие, увеличиваются их продуктивность и доход компании;

• для внешней документации: разгружает сотрудников техподдержки.

---

Хорошая ли у вас документация?

Пройдите маленький тест и посчитайте набранные баллы:

Результаты:

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

Не торопитесь переходить к действиям — сначала налейте чай и просто прочитайте статью.

---

Шаг 1. Соберите всю информацию

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

• старая документация;

• личные страницы — ваши и коллег (например, в Confluence);

• ответы в чатах;

• репозитории (например, в GitLab);

• Word и другие текстовые редакторы;

• ссылки в закладках браузера.

На будущее: никогда не дублируйте инструкции в разных ресурсах, так их будет сложнее поддерживать: 

• легче обновить одну, чем две;

• одну из версий точно забудут обновить — и она будет вводить в заблуждение; как назло всегда будут находить именно её.

---

Шаг 2. Выбросите мусор

Одна актуальная статья лучше десяти устаревших.

Проверено: если у вас в документации найдут устаревшие сведения, никто не будет читать дальше — спросят у вас лично.

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

Под «избавлением» имеется в виду одно из двух:

• добавление в архив — предпочтительно;

• безвозвратное удаление.

Если после этого вообще ничего не осталось, это нормально.

Если вы детально не знаете начинку описываемой технологии

После такой «чистки» обычно очень легко дышится — будто камень с шеи снял.

---

Шаг 3. Найдите частые вопросы и сценарии

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

1. Вы перечитываете все вопросы в чате за последний месяц, выписываете их на отдельную страницу (не удаляйте её) и считаете их количество. 

2. Читаете комментарии с вопросами под инструкциями, если есть.

3. Опрашиваете аудиторию. Обычно это либо пост в публичном чате, либо вопросы знакомому коллеге лично. Формы с опросами, как правило, неэффективны, поскольку собирают мало ответов.

4. Продумываете популярные сценарии с командой, ведь лучше вас продукт никто не знает.

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

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

---

Шаг 4. Поделите на разделы

Цель — наметить примерный план будущей базы знаний. Он может дополняться, когда появятся новые данные, но пока нужно сделать «скелет» для всего остального. 

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

Добавить их все сплошным списком вразнобой — провальный вариант. Ctrl+F тут тоже не всегда поможет, потому что, например, вы пишете в названии страницы «кубер», а ваш читатель ищет «Kubernetes» или «k8s», ничего не находит — и идёт к вам в личку.

Целевая аудитория

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

Подумайте, какие люди будут её читать. Например:

• только ваша команда;

• другие команды, им нужна одна функциональность;

• другие команды, им нужна разная функциональность;

• и ваша команда, и другие команды.

Внешние команды не должны видеть странички «Черновик to do», «[убрать в архив] 2 декабря». Держите их в отдельной папке для черновиков.

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

---

Шаг 5. Составьте словарь терминов

Одна сущность — один термин.

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

Термины должны легко находиться через Ctrl+F.

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

---

Шаг 6. Утвердите правила для команды

Заранее обговорите с командой правила и план ведения документации.

• нет структуры — статьи добавляют куда попало;

• никто не убирает устаревшую информацию;

• команда не всегда знает, что у неё есть в документации;

• много заброшенных статей;

• много пустых статей из 2016 с пометкой «to do»;

• перемешаны внутренние черновики и внешняя документация;

• нет архива;

• ведётся на русском, английском, латинском и древнегреческом.

Донесите до команды, что документация — это ваш общий продукт и от её качества зависит эффективность: ваша и других команд.

Пример правил по созданию новых страниц:

Советую почитать о методике совместного ведения документации.

---

Шаг 7. Напишите тексты

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

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

• Освойте инструменты форматирования там, где вы ведёте документацию. Примеры: макросы Confluence, синтаксис Markdown и HTML.

  

• Укажите, для кого страница и что в ней описано, — тогда человек сразу поймёт, нужно ли ему это читать.

• Не пишите сплошные тексты — делите их на логические абзацы и разделы. При грамотной вёрстке легче сходу найти ответ.

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

• Оформите разводящую страницу. Это главная страница с основной информацией и разделами по темам. Она нужна, чтобы читатель быстро понял, где искать необходимую инструкцию.
  Пример Ozon Docs
  Пример Yandex Cloud
  Пример Amazon EC2

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

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

• Избегайте канцеляризмов — они утяжеляют тексты: «для того чтобы в данном процессе осуществить определённую функциональность».

• Выделяйте в тексте важное, но не превращайте его в одни сплошные плашки.

• Укажите контакты команды, чтобы читатели знали, к кому обращаться.

---

Шаг 8. Добавьте FAQ

FAQ — страница с часто задаваемыми вопросами и ответами на них. 

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

Используйте список из шага 3, если он есть.

FAQ — это не полноценная инструкция. Не дублируйте тексты и не делайте ответы очень подробными. 

Оптимальный вариант — краткий ответ со ссылкой на полную инструкцию. Например, «Да, это возможно. Подробнее в статье “Как создать N”».

Для продвинутых идеалистов:

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

---

Шаг 9. Продумайте, как вашу документацию будут находить

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

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

• к вам в личку: закрепите ссылку на документацию у себя в профиле на корпоративном портале;

• в ваш чат: закрепите ссылку в шапке, закреплённом сообщении, сделайте так, чтобы каждому вступившему ссылку отправлял бот;

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

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

---

Шаг 10. Проанализируйте результат

Лучший источник для анализа — ваша аудитория. 

Есть несколько способов понять, решает ли проблемы ваша документация.

Что обычно делаю я:

• Считаю количество запросов в чатах. 

• Провожу мини-исследование среди читателей: готовлю открытые вопросы, спрашиваю, долго ли они искали информацию, что именно они искали, нашли ли ответы на свои вопросы.

• Изучаю статистику просмотров в Confluence и Grafana: если за месяц никто не обратился к документации, нужна ли она?

Сама не практикую, но отличная идея:

• Добавить фичу «Оцените статью». Такие макросы точно есть в Confluence.

Если на этом этапе не всё гладко — это нормально, просто будьте готовы что-то дописать, поменять местонахождение статьи.

---

Итог

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

И помните, что документация — ваш общий продукт. 

Буду рада ответить на ваши вопросы. Делитесь мнением и историями в комментариях.

Перевод статьи
«Writing Good Documentation for Your Open-Source Library».

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

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

Еще одна причина того, почему разработчики
осознали важность документации, состоит
в конкуренции библиотек в экосистемах.
До наступления эры npm эта проблема не
стояла так остро. Например, в Python обычно
бывает только один способ сделать
что-либо. В JavaScript, до прихода Node, также
не было большого числа библиотек, которые
выполняли бы одну и ту же функцию разными
способами. Вот попытайтесь припомнить
какие-нибудь популярные альтернативы
jQuery!

А сегодня мы можем выбирать себе
технологический стэк. Поэтому разработчики
библиотек и фреймворков прилагают
значительные усилия, чтобы максимально
облегчить потенциальному пользователю
изучение и использование их продуктов.
JavaScript-разработчики могут выбирать между
Angular, React, Vue и другими, менее популярными
фронтенд-фреймворками, а также между
Express, Koa или Sails в бэкенде. И это еще если
не считать миллионы других библиотек,
занимающих промежуточное положение!

Из чего состоит хорошая
документация

Документация проекта состоит из многих
вещей. Например:

• Файл README
• Справочная информация
• Руководство пользователя
• Сборник рецептов
• Посты в блоге

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

README

Файл README это, зачастую, первая возможность потенциальных пользователей познакомиться с вашим продуктом. В нем могут содержаться сведения, характерные для разных типов документации (справочника, руководства и т.п.), но при этом файл README не спутаешь ни с чем другим. Этот файл помогает вам «продать» вашу open-source библиотеку. При этом не забывайте, что текст README должен быть кратким и информативным.

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

Если ваш файл длиннее одной или полутора
страниц, будет хорошим тоном добавить
содержание (список контента).

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

Наконец, включите в ваш файл README
сведения о лицензии продукта и список
контрибьюторов. Можно также добавить
параграф о том, как принять участие в
разработке вашей библиотеки. Помните,
что одним из столпов open-source является
уважение ко времени других людей. Если
ваши потенциальные контрибьюторы смогут
быстро разобраться в работе вашей
библиотеки, от этого выиграют все.

Справочная информация

Справочные материалы это, пожалуй,
самая техническая часть вашей документации.
Ее предназначение — перечислить весь
список функций вашей библиотеки, их
ожидаемые input-ы, output-ы и побочные эффекты,
а также назначение и примеры реализации.
Примеры в справочнике должны быть
максимально изолированными и
самодостаточными.

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

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

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

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

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

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

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

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

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

Сборник рецептов

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

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

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

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

Посты в блоге

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

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

Учтите, что несмотря на название
раздела, это может быть не пост в блоге
в буквальном смысле. Вы можете сделать
все вышесказанное на GitHub Gist и поместить
ссылку в файл README.

Перед публикацией

Вычитка документации обязательна.
Чтение документации с грамматическими
и пунктуационными ошибками быстро
утомляет. Обдумайте возможность дать
вычитать вашу документацию носителю
английского языка или кому-то, кто хорошо
знает этот язык. Если этот вариант
недоступен, дайте возможность вашим
контрибьюторам делать пул-реквесты по
документации и отдельно попросите их
об этом в README. Также к вашим услугам
большое количество автоматизированных
инструментов, например, Grammarly
или Hemingway.

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

Заключение

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

Ну и, в конце концов, писать документацию не так уж и страшно!

 vlada_maestro / shutterstock

Пишет о программировании, в свободное время создаёт игры. Мечтает открыть свою студию и выпускать ламповые RPG.

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

Содержание

• Два вида документации
• Правила хорошего тона в составлении документации
• Где писать документацию в C#
• Как создать файл документации
• Заключение

Разработчики имеют дело с двумя основными видами документации:

1. Пользовательская документация. Это руководство по эксплуатации программ. Обычно оно нужно для сложных профессиональных инструментов. Если же пользователи не могут сами разобраться в приложении пиццерии, то лучше доработать интерфейс — добровольно никто инструкцию читать не станет.
2. Техническая документация. Это пояснения для программистов, которые будут использовать или дорабатывать существующий код. Они помогут быстро вникнуть в проект и начать работать. Или же продолжить писать программу после долгого перерыва.

К сожалению, не все разработчики (практически никто) любят читать документацию. Любителей писать её и того меньше. Однако делать это очень важно, потому что сложно поддерживать проект без документации.

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

1. Документация нужна не всегда

Если программа одноразовая, не стоит тратить время на написание пояснений. Например, если нужен небольшой скрипт, который будет написан за пять минут и использован 1-2 раза.

2. Документация нужна не везде

Также не нужно писать пояснения ко всему. Если код написан хорошо, то по названиям уже будет понятно, что это такое и зачем оно используется. Например, легко догадаться, что метод int Sum (int a, int b) возвращает результат сложения двух чисел.

Исключение можно сделать, если речь идет об API или фреймворке, которыми пользуются многие разработчики: они не всегда видят исходный код, но могут использовать классы и методы. Поэтому им важно иметь список доступных методов. В этом случае задокументировать всё нужно просто для галочки.

3. Документация должна быть точной

Очень важно уметь ясно выражать свои мысли. Нужно предельно точно описывать, что делает тот или иной фрагмент кода. Для этого стоит давать как можно более короткие определения. Например:

/// <summary>
/// Сообщение в чате. 
/// </summary>
class Message
{
	…
	/// <summary>
	/// Текст сообщения. 
	/// </summary>
	public string Text
	{
		get { return this.text; }
}
}

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

4. Документация должна быть сухой

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

5. В документации не должно быть старого кода

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

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

Если есть сомнения пригодится ли еще этот код, его лучше сохранить в системе контроля версий — именно для этого ее и придумали.

Дальше речь пойдет о том, как писать техническую документацию для программ на C#. Вся работа будет вестись в Visual Studio.

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

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

В C# есть два вида комментариев. Однострочные:

int a = 11 + 12; //Это однострочный комментарий

И многострочные:

/* Начало комментария
Это
Многострочный
Комментарий
Конец комментария */

Компилятор во время сборки игнорирует комментарии и просто вырезает их, поэтому на работу программы они не влияют.

Более продвинутый вариант — использовать XML. Чтобы вставить XML-комментарий, нужно перед названием класса, поля, свойства или метода поставить тройной слеш.

После этого автоматически будет создано два элемента:

1. Summary — общий комментарий. В нем пишут, что делает метод или для чего нужен класс.
2. Param — комментарий об аргументе. В нем указывается, какое значение надо передать.

Практически все инструменты, в том числе и Visual Studio, поддерживают вывод подсказок, которые подгружаются из документации. И теперь, если навести на метод Main () или его аргумент, то можно увидеть, что было написано в комментарии.

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

Еще можно использовать такие XML-элементы, как:

• Returns — возвращаемое значение;
• Value — значение свойства;
• Exception — исключение;
• Remarks — ремарка к основному комментарию.

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

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

Для этого сначала нужно зайти в настройки проекта:

А потом перейти во вкладку Build и поставить галочку XML documentation file:

Теперь вместе с компиляцией программы будет создаваться файл с документацией в формате XML. Его можно преобразовать в HTML с помощью специальных утилит. Microsoft для этого рекомендует использовать DocFX или Sandcastle.

Рассмотрим на примере DocFX. Его можно скачать с помощью NuGet Package Manager в Visual Studio. Для этого нажмите на проект правой кнопкой мыши и выберите пункт Manage NuGet Packages:

Затем перейдите во вкладку Browse и введите в поле поиска название docfx.console, а потом нажмите Install:

После нужно подтвердить установку и согласиться с условиями лицензионного соглашения.

Теперь при сборке проекта будет создаваться папка _site, в которой находится сайт с документацией. Однако это касается класса Program, поэтому чтобы проверить работу DocFX, нужно добавить какой-нибудь класс:

namespace ConsoleApp1
{
	/// <summary>
	/// Класс, который представляет пользователя.
	/// </summary>
	public class User
	{
		private string name;

		/// <summary>
		/// Конструктор класса.
		/// </summary>
		/// <param name="name">Имя пользователя.</param>
		public User(string name)
		{
			this.name = name;
		}

		/// <summary>
		/// Меняет имя пользователя.
		/// </summary>
		/// <param name="name">Имя пользователя.</param>
		public void ChangeName(string name)
		{
			this.name = name;
		}

		/// <summary>
		/// Метод для вывода имени пользователя.
		/// </summary>
		/// <returns>Возвращает имя пользователя.</returns>
		public string GetName()
		{
			return this.name;
		}

	}
}

После компиляции проекта с таким классом можно проверить сайт. Его главная страница будет пуста — она нужна для того, чтобы вкратце описать свою программу. Сама же документация находится по адресу api/index.html.

Вот как она выглядит:

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

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

Была ли эта статья полезной?