Документация — это всегда проблема. Писать для широкой аудитории нелегко, как и найти подходящее решение для публичной документации. Нужно учесть множество аспектов: не только внешнее оформление, но и функциональные возможности, а также затраты, техническую поддержку и требуемые усилия. Написание одинаковой документации в одном инструменте может занять гораздо больше времени, чем в другом. Попробуйте представить один и тот же текст в формате языка разметки и в редакторе форматированного текста — что вам больше подходит?
С одной стороны, есть решения, размещаемые на собственном сервере, — от Vuepress до Docsify. Использование таких решений с открытым исходным кодом имеет смысл для компаний с открытым исходным кодом. Однако при размещении на собственном сервере возникает необходимость в дополнительном обслуживании, написании пользовательских функций, создании стиля и/или дизайна и т. д. Небольшая компания не может позволить себе тратить время на техническую поддержку или даже создание сайта, который можно сделать практически необслуживаемым с минимальными усилиями.
С другой стороны, предлагаются размещенные на сторонних ресурсах платформы, такие как Gitbook и Readme. Эти платформы идеально подходят для быстрого выпуска документации, хостинга и обновлений. Кроме того, с ними можно не беспокоиться об управлении.
Выгодно ли использовать собственный инструментарий? Важно правильно оценивать свои сильные и слабые стороны. К примеру, Budibase не создавалась для хостинга документации, а внимание ее разработчиков было сосредоточено на инструментах администрирования, формах и внутренних приложениях.
Итак, команда Budibase обратилась к размещаемым решениям. На этом поле есть несколько игроков. О двух из них — Gitbook и Readme — уже упоминалось. Обсудим оба эти решения, их преимущества и недостатки.
До недавнего времени Gitbook устраивал Budibase. Это отличное расширение для размещения документации на Github. Gitbook использует ветки, позволяет совместно работать над проектом и ориентирован на открытый исходный код (несмотря на то, что больше не обладает открытым исходным кодом). Отправка PR на Github безупречна с Gitbook. Дизайн размещенного решения Gitbook довольно прост и понятен пользователям.
Но в случае Budibase на этом преимущества Gitbook заканчиваются. Gitbook медленно загружается не только в бэкенде, но и у пользователей. Кнопка редактирования в его интерфейсе срабатывает медленно. Экран редактирования открывается только после того, как загружается для создания новой ветки в фоновом режиме, что замедляет работу. Такого рода задержки становятся помехой, когда приходится редактировать несколько страниц.
Еще одним недостатком, который в значительной степени можно отнести к субъективным факторам, является дизайн. Gitbook довольно стандартен и выглядит немного устаревшим. И хотя сервисы документации, размещенные на Readme и Gitbook, выглядят практически одинаково, разница в стиле довольно ощутима. Вероятно, это дело вкуса.
Прежде чем сделать выбор между Readme и Gitbook, обязательно ознакомьтесь с обоими инструментами! Оба предоставляют пользователям бесплатные версии. А учитывая, что оба они основаны на Markdown, переключиться с одного на другой будет довольно просто.
Итак, о переходе. Команда Budibase собиралась развернуть новый API, а документация по API — сложная задача, требующая правильного выполнения. Написание собственных справочных таблиц, примеров и руководств с четким обзором — это не то, что можно сделать за один раз.
Readme предложила Budibase решение — OpenAPI-2-Documentation. В противном случае команде пришлось бы потратить массу времени на документирование API, и она уже рассматривала возможность использования Postman для размещения спецификации API. Но в итоге разработчики предпочли, чтобы спецификация API была интегрирована в документацию. Как выяснилось, Readme может еще больше за счет интеграции и предварительного заполнения ключей авторизации.
Это лучшее доказательство того, почему нужно выбирать правильный инструмент для работы. Если бы Budibase написала документацию на Gitbook, то, вероятно, на это потребовалась бы неделя, а нужный результат так и не был бы достигнут. Перенос всей существующей документации на Readme занял меньше недели, и в итоге получилось более простое решение для пользователей.
После переноса документации на Readme команда изменила настройки DNS. Через час на новом сайте появился первый трафик. Все оказалось довольно просто (за исключением того, что некоторые страницы не были перенесены, и пришлось немедленно все переписывать).
Единственное, что еще не готово спустя несколько дней после перехода на Readme, — это переиндексация в Google. Это один из минусов перехода с одной платформы на другую — у вас нет контроля над URL, а это имеет значение для решения SEO-задач.
После запуска
Спустя неделю работы на Readme команда Budibase уже наблюдала хороший трафик к документации — тысячи просмотров страниц, которые можно проанализировать.
Аналитическая часть Readme намного понятнее и обширнее, чем у Gitbook. Она позволяет видеть, куда люди переходят и что ищут. Не стоит недооценивать опции “Помогла ли вам эта страница?” с поднятыми и опущенными вверх/вниз пальцами внизу страницы. Они дают полезную информацию о том, где люди не нашли нужную им информацию, какие страницы и руководства нужно написать с учетом этого и как действовать дальше.
Еще одним замечательным преимуществом является то, что пользователи могут рекомендовать улучшения в документации. Для этого на странице есть кнопка, а вместе с предложением появляется кнопка “объединить” (“merge”). Если пользователь хотел сделать это с помощью Gitbook, то сначала попадал в репозиторий документации, затем должен был снова найти ту же страницу и предложить изменения через PR. Та же процедура с Readme намного проще, что обеспечивает лучший пользовательский опыт.
Заключение
В конечном счете, все, что имеет значение, — это выбор правильного инструмента для работы. Если вам нужен инструмент только для документирования и достаточно таких возможностей, как статичные файлы с разметкой, вы будете очень довольны Gitbook или собственным сервером.
Читайте также:
- Как написать впечатляющий Readme-файл для проекта
- Основы написания мануалов при разработке
- Две малоизвестные, но полезные команды npm
Читайте нас в Telegram, VK и Яндекс.Дзен
Перевод статьи Rene Pot: Why we’ve moved from Gitbook to Readme
