Всё для технического документирования
+7 (495) 001-40-42
Разработка технической документации
Курсы для технических писателей
Программное обеспечение

Читерские коды для хорошей документации (часть 1)

25.06.2014

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


 

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

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

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

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

Исследование Programmable Web’s API показывает, что «полная и точная документация» оценивается как наиболее важный фактор для людей, которые пользуются API. Она оценивается даже выше, чем безотказная работа и надёжность. Подумайте об этом пару минут. Сколько людей у вас в команде отвечают за безотказную работу и отзывчивость? Сколько людей состоит в службе поддержки клиентов, отвечая за то, чтобы клиенты получали быстрый ответ? А сколько людей работают над потребительской документацией, которая так же важна, если даже не больше?

Давайте разберёмся. Плохая документация вызовет все виды проблем, когда код и клиентская база вырастут. Даже если вам удастся получить клиентов, несмотря на плохие документы, они будут регулярно звонить, писать в чате и по электронной почте в службу технической поддержки, чтобы та дополнила (или, для некоторых клиентов, заменила) документацию. Кевин Берк из Twilio подводит итог в своём блоге под названием «Не экономьте на документации»: «Так же, как быстрое черновое кодирование может привести к техническим проблемам, плохая документация может привести к оперативным проблемам». И даже в рамках компании при обмене информацией между разработчиками и службой поддержки, плохие документы могут замедлить написание кода. А с хорошей документацией новые сотрудники имеют надёжный источник информации, который поможет им понять продукт, над которым они будут работать.

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

Что делает документацию хорошей?

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

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

Цели документации

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

02

Сделать из пользователей героев

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

Позволить клиентам справляться самим

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

Уменьшить расходы на поддержку

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

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

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

Описательная

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

Технический справочник и код

Скучная рутина, как что-то работает, включая описание всех конечных точек API, методов и параметров, наряду с примерами запросов и ответов. Также включает образец кода.

Учебные материалы

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

Интерактивная

Такие системы как Mashery I/O DocsSwagger и т.д. позволяют тестировать запросы API или писать код прямо в браузере. Дайте людям возможность опробовать систему без необходимости писать код (и необходимости уметь писать код).

(продолжение следует)

Источник:Cheat Codes for Good Documentation

Тэги: , , ,

< Вернуться к списку публикаций

Облако тегов