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

26.06.2014

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

Большое количество документации – проблема разработчиков

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

Три из четырёх категорий требуют участия разработчиков, и мы обнаружили, что это работает не только в теории, но и на практике: в хранилище документов компании SendGrid около 230 HTML-страниц, но больше 2100 блоков кода. Эти коды писали кодеры, а не писатели. Если ваши разработчики будут заинтересованы в документации, то они будут заинтересованы и в её создании с точки зрения её содержания. И конечно, если вы захотите настроить под себя платформу, на которой создано хранилище документации, вам нужен разработчик.

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

Документация как программное обеспечение

Структура и постоянство

Условные обозначения являются необходимым условием для всех проектов по разработке. Такие вещи, как расположение файлов, именования CamelCase против snake_case, табуляция против пробелов и так далее должны быть согласованы, чтобы все понимали, что делают и имели представление о том, чего ожидать. По тем же причинам ваша документация должна иметь чётко определенную структуру, и форматирование должно быть одинаково на всех страницах. Разделы, содержащие дочерний контент, должны быть легко узнаваемы. Описания параметров должны выглядеть одинаково от страницы к странице. Образцы кода должны быть хорошо отформатированы и легко читаться.

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

Документы изменяемы

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

Вам придётся встроить умные ограничения в систему. Для SendGrid цель была в том, чтобы иметь статический сайт, для чего мы выбрали платформу Jekyll, которая сама по себе ставит для нас ограничения. Такие вещи, как автоматизированная проверка ссылок и тесты валидности разметки могут помочь держать ситуацию под контролем по мере роста проекта.

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

Не повторяйтесь

Глупые грибы…

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

Не делайте крепких привязок

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

Держите под контролем обратную связь

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

Битва с боссом

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

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

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

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

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

Вы апнули уровень. Идите и проверьте свою мощь!

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

Тэги: API, опыт, советы, эффективность