Читерские коды для хорошей документации (часть 1)
Брендон Уэст – разработчик-идеолог в компании SendGrid – необычный человек. Согласитесь, не часто встретишь разработчика, который заботится о качестве документации, да ещё и пропагандирует такой подход среди коллег. Сегодня мы познакомимся с его статьёй о важности качественной документации.
Все, особенно разработчики, обожают работу над документацией. Они понимают важность документов и их влияние на принятие покупателем продукта и опыт клиента. Они всегда учитывают документацию при планировании и выпуске кода. Постойте, над чем это вы смеётесь?
У многих компаний есть проблемы с документацией. Из-за огромного количества типичных проблем сложно отстоять документацию; информация устаревает, ей не хватает полноты, контент плохо организован и противоречив, читатели не могут найти то, что ищут, а образцы кода могут быть неверными. Если вы зайдёте в отдел разработки и попросите добровольцев для обновления документации, вас встретят тишиной, если не откровенной насмешкой.
Правда в том, что нет читерских кодов, чтобы создать культуру, где ценят документацию, или чтобы создавать качественный контент, но я хочу поделиться практическими уловками, которым я научился, пытаясь создавать такую культуру для сервиса SendGrid. Надеюсь, я подарю вам пару дополнительных жизней (ну или хотя бы дополнительное здоровье) в этой игре.
Почему документация важна
Исследование Programmable Web’s API показывает, что «полная и точная документация» оценивается как наиболее важный фактор для людей, которые пользуются API. Она оценивается даже выше, чем безотказная работа и надёжность. Подумайте об этом пару минут. Сколько людей у вас в команде отвечают за безотказную работу и отзывчивость? Сколько людей состоит в службе поддержки клиентов, отвечая за то, чтобы клиенты получали быстрый ответ? А сколько людей работают над потребительской документацией, которая так же важна, если даже не больше?
Давайте разберёмся. Плохая документация вызовет все виды проблем, когда код и клиентская база вырастут. Даже если вам удастся получить клиентов, несмотря на плохие документы, они будут регулярно звонить, писать в чате и по электронной почте в службу технической поддержки, чтобы та дополнила (или, для некоторых клиентов, заменила) документацию. Кевин Берк из Twilio подводит итог в своём блоге под названием «Не экономьте на документации»: «Так же, как быстрое черновое кодирование может привести к техническим проблемам, плохая документация может привести к оперативным проблемам». И даже в рамках компании при обмене информацией между разработчиками и службой поддержки, плохие документы могут замедлить написание кода. А с хорошей документацией новые сотрудники имеют надёжный источник информации, который поможет им понять продукт, над которым они будут работать.
Документы – своего рода маркетинговые материалы для разработчиков. Я не говорю, что вам надо наполнить документы рекламными материалами или выбирать фразы на основе целей SEO. Я имею в виду, что если у вас хорошая документация, вы завоюете уважение и доверие целевой аудитории. Если документы у вас плохие, вряд ли вы сможете создать впечатление, что весь сервис надёжен и хорошо построен.
Что делает документацию хорошей?
Если я и могу что-то объективно утверждать, так это то, что вы не сможете угодить всем. Независимо от того, какие критерии вы определяете или как прекрасно структурируете документ, кто-нибудь найдёт то, что ему не понравится.
Всё остальное субъективно и в какой-то степени предполагает собственное мнение и опыт, основанный на наблюдениях. Я знаю, что документацию SendGrid можно улучшить; я думаю, нужно постараться, чтобы найти более сурового критика нашей документации, чем я. То есть, я думаю, что мы достигаем наших целей и движемся в правильном направлении. То, что я расскажу далее, я узнал в то время, когда искал направление и способы повернуть паруса в этом направлении.
Цели документации
Следующие цели достаточно широки, но они – отличное мерило для определения того, что должно и чего не должно быть в документации. Если контент, над которым вы работаете, не выполняет, по крайней мере, одну, а тем более несколько из этих целей, сделайте шаг назад и подумайте над ним ещё.
Сделать из пользователей героев
Дайте пользователям оружие, которое им нужно, чтобы быстро делать то, что им нужно. Документы должны позволить читателям понять и воспользоваться вашими разработками, чтобы они могли убить любых демонов, с которыми борются.
Позволить клиентам справляться самим
Разработчики – люди, которым нужно, чтобы всё работало. Они не хотят звонить или писать по электронной почте, или использовать чат, чтобы выяснить, как сделать что-то, если этого можно избежать, потому что это замедляет работу. Хорошая документация является источником света, который позволяет разработчикам окунуться в неизвестность, не боясь монстров.
Уменьшить расходы на поддержку
Разработчики не хотят звонить и писать, и использовать чаты, при этом снижение количества заявок в поддержку также означает снижение расходов для бизнеса. Пусть клиенты смогут с вами связаться, когда вы им нужны, но позвольте им нуждаться в вас реже.
Категории документации
Для достижения этих целей мы должны обеспечить разнообразие типов документации. Мои старания свелись к выделению четырёх категорий.
Описательная
Возможно, самый традиционный вид маркетинговых документов. Они описывают, какие проблемы вы решаете, как вы их решаете, и какие выгоды получит клиент, внедрив ваше решение.
Технический справочник и код
Скучная рутина, как что-то работает, включая описание всех конечных точек API, методов и параметров, наряду с примерами запросов и ответов. Также включает образец кода.
Учебные материалы
Разработаны, чтобы привести пользователя из исходной точки к рабочей системе, что обеспечит достижение определённого сценария использования.
Интерактивная
Такие системы как Mashery I/O Docs, Swagger и т.д. позволяют тестировать запросы API или писать код прямо в браузере. Дайте людям возможность опробовать систему без необходимости писать код (и необходимости уметь писать код).
Источник:Cheat Codes for Good Documentation
Тэги: API, опыт, советы, эффективность
- API
- DITA
- Flare
- HTML
- MadCap
- MS Word
- XML
- Алисса Фокс
- Марк Бейкер
- ПроТекст
- Том Джонсон
- анализ
- блоги
- веб-контент
- видеоролики
- единый источник
- изображения
- инструкции
- инструменты
- исследование
- качество контента
- командная работа
- конференции
- локализация/перевод
- минимализм
- навыки
- обучение
- опыт
- организация работы
- продвижение
- профессия
- редактирование
- роли
- советы
- стиль
- структурированное писательство
- теория документирования
- управление контентом
- форматирование
- форматы
- ценность контента
- эджайл
- эффективность
- юмор