Как Twilio создают документацию

Пересказ доклада Twilio про пределывание их документации. Полностью доклад можно посмотреть в одном из видео (раз и два, содержание на 80% совпадает) или почитать у них в блоге.

Предыстория

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

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

Поэтому Twilio стали придумывать code-first документационные решения, которые будут рассказывать разработчикам как пользоваться их сервисом через код.

Инструменты

Для сайта документации они использовали:
- Wagtail CMS на базе Django. С помощью инструмента StreamField можно комбинировать структурированные и неструктурированный контент. Twilio используют этот инструмент для вставки примеров кода в документацию.
- Github, где хранят все примеры кода в отдельном репозитории и тестируют их как настоящий код. А еще получают PR от внешних разработчиков, которые попробовали пример кода и знают, как его можно улучшить.

Для аналитики и исследований:
- Optimizely для а/б тестирования.
- MixPanel и Google Analytics для метрик.
- UserTesting для видео интервью с разработчиками.

Еще несколько открытий Twilio про поведение разработчиков

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

#developerexperience