О запуске документации легче сказать, чем сделать. Мало того, что существует множество мест для размещения документации, но и инструменты, которые вы получаете, также сильно различаются.
Документация сложная. Не только потому, что писать для широкой аудитории непросто, но и потому, что поиск правильного решения для вашей (общедоступной) документации может стать настоящей проблемой. Есть так много аспектов, которые нужно иметь в виду. Не только то, как все выглядит, но и то, к каким функциям вы получаете доступ, цены, обслуживание и усилия, необходимые для написания. Да, написание одной и той же документации в одном инструменте может занять гораздо больше времени, чем в другом. Попробуйте написать тот же текст с уценкой или с помощью редактора форматированного текста, что вам больше подходит?
С одной стороны спектра находятся самостоятельные решения, от Vuepress до Docsify и многие другие. Использование собственного решения с открытым исходным кодом имело бы большой смысл, поскольку мы сами являемся компанией с открытым исходным кодом. Тем не менее, самостоятельный хостинг предполагает дополнительное обслуживание, пользовательские функции, которые вам нужно написать, стили и / или дизайн, которые вам нужно сделать, и многое другое. Учитывая, что мы всего лишь небольшая компания, мы не можем позволить себе тратить часы на поддержку или даже на создание веб-сайта, который можно сделать практически не требующим обслуживания с минимальными усилиями.
С другой стороны, это размещенные платформы, такие как Gitbook и Readme. Эти платформы отлично подходят для быстрого развертывания документации, управления хостингом и обновлениями для нас и беззаботной ситуации в отношении управления.
Хотели бы мы использовать наш собственный инструментарий Budibase? Ну не совсем. Budibase не был создан для размещения документации; Budibase намного сильнее в инструментах администрирования, формах и внутренних приложениях. Вы должны знать свои сильные и слабые стороны!
Итак, мы обратились к хостинговым решениям. И на поле есть несколько игроков. Я уже упоминал два таких решения; Gitbook и Readme, и оба они мы собираемся обсудить здесь. У обоих есть преимущества и недостатки, но для нас есть явный победитель.
Gitbook был нашим предпочтительным инструментом до недавнего времени. Это отличное дополнение к документации, размещенной на Github; он использует ветки под капотом, допускает совместную работу и очень ориентирован на открытый исходный код (несмотря на то, что их инструмент больше не является открытым исходным кодом). Даже отправка PR на Github хорошо работает с Gitbook. Дизайн размещенного решения Gitbook также довольно прост, но понятен пользователям. Хотя для нас на этом преимущества заканчивались. Gitbook загружался медленно, не только в бэкенде, но и у наших пользователей. Даже нажатие кнопки редактирования в интерфейсе Gitbook было медленным. Он не сразу открывал экран редактирования, но загружался для создания новой ветки в фоновом режиме, прежде чем фактически отображать экран, что делало работу относительно медленной. Такие задержки в конечном итоге приводят к легкому раздражению, когда вы пытаетесь отредактировать несколько страниц.
Еще одним недостатком, о котором очень много мнений, был дизайн. Gitbook довольно упрощен и не очень вдохновляет, и в этом отношении он также кажется немного устаревшим. Не то, чтобы устаревшее имело большое значение, но в целом ощущение было не тем, что мы ищем. И хотя как для Readme, так и для Gitbook все сайты с документацией, размещенные на них, выглядят одинаково, есть огромная разница в стиле. Возможно, у нас просто разные вкусы, но для нас одна вещь, которую мы постоянно повторяли при настройке Readme; «Чувак, Readme выглядит красиво».
Не поймите меня неправильно, Gitbook по-прежнему является отличным решением, и я по-прежнему рекомендую его. Gitbook просто не для нас. Поэтому, прежде чем принять решение о моей статье, обязательно ознакомьтесь с ними обоими! У них обоих есть отличные бесплатные уровни, поэтому нет абсолютно никаких причин не попробовать их оба перед совершением. И, учитывая, что они оба основаны на Markdown, переключаться тоже должно быть довольно легко.
Так вот про этот переключатель. Совсем недавно мы решили поменяться. Мы собирались внедрить новый API, который мы только что выпустили, а документация API — сложная вещь, которую нужно сделать правильно. Написание собственных справочных таблиц, примеров и руководств с четким обзором — это не то, что вы делаете на скорую руку. Затем появился Readme и дал нам решение OpenAPI-2-Documentation. Кто мы такие, чтобы игнорировать этот фантастический факт. Мы бы потратили много времени на документирование API и рассмотрели бы возможность использования Postman в качестве решения для размещения нашей спецификации API. Тем не менее, в конце концов, мы бы предпочли, чтобы спецификация API была интегрирована в документацию. И Readme может даже улучшить это за счет интеграции и предварительного заполнения ключей аутентификации. Мы еще не добрались до этой последней части, но мы это сделаем.
Это отличное доказательство того, почему вам нужно выбрать правильный инструмент для работы. Если бы мы остановились на Gitbook и написали там документацию по API, мы, вероятно, потратили бы на это неделю и сделали бы это плохо. Однако перенос всей нашей существующей документации занял меньше недели, и в итоге мы получили более простое в использовании решение для наших пользователей. И, как упоминалось ранее, мы могли бы также разместить нашу спецификацию API в Postman, но тогда у нас было бы два разных места, где наши пользователи могли бы найти информацию, и это может сбить с толку.
Итак, мы перенесли наши документы, и когда все было хорошо, мы изменили настройки DNS. Час спустя новый веб-сайт увидел первый трафик. Я немного нервничал, все шло хорошо, но все оказалось довольно просто. За исключением некоторых страниц, которые не переносятся, или побуждения немедленно все переписать.
Единственное, что еще не завершено, через несколько дней после того, как все было изменено, — это переиндексация Google. Это, конечно, один из недостатков перехода с хостинговой платформы на хостинговую платформу; у вас нет контроля над URI, и это важно для целей SEO. К счастью, в итоге результат должен быть лучше, а не хуже. Поэтому приходится идти на необходимые жертвы. Если бы у вас была возможность самостоятельно разместить документацию, вы, вероятно, смогли бы сохранить все URL-адреса нетронутыми.
После запуска
Итак, мы в эфире, уже около недели, и мы видим хороший трафик, попадающий в документацию. Тысячи просмотров страниц уже были зарегистрированы, и это дает нам некоторые полезные сведения.
Аналитическая часть Readme также намного понятнее и обширнее, чем Gitbook. Мы ясно видим, куда люди перемещаются, что люди ищут в нашей документации, и не должны недооценивать поднятие/опускание большого пальца «Помогла ли вам эта страница» в нижней части страницы. Мы уже получаем хорошее представление о том, где люди не нашли информацию, которую они ищут, какие страницы и руководства нам нужно написать, чтобы приспособиться к этому, и как действовать дальше.
Еще одним удивительным дополнением является то, что пользователи могут рекомендовать улучшения в документации. Для этого на странице есть хорошая кнопка, и с этим предложением идет простая кнопка «объединить». Раньше, если пользователи хотели сделать это с помощью Gitbook, вы попадали в наш репозиторий документов, должны были снова найти ту же страницу и предлагать изменения через PR. Процесс Readme намного более плавный и обеспечивает гораздо лучший пользовательский опыт.
Заключение
Так что да, большое спасибо команде Readme, создавшей потрясающую платформу для документации. Мы очень счастливы использовать его прямо сейчас. И хотя мы не были недовольны Gitbook, переход действительно дает нам душевное спокойствие. Но, в конце концов, все, что имеет значение, — это выбрать правильный инструмент для работы. Если вы простодокументируете инструмент и вам не нужны дополнительные функции, кроме статических файлов уценки, вы будете очень довольны Gitbook или самостоятельным размещением.
Мы в Budibase теперь можем уделять больше времени тому, что мы должны делать, создавая отличный инструмент с открытым исходным кодом и минимальным кодом. А лично для меня? Теперь я могу сосредоточить свое время на улучшении документации, информировании и поддержке там, где это необходимо.
Мне очень интересно, что вы думаете. Вы бы сделали то же самое? Или что-то совсем другое? "Дайте мне знать"!
Повышение уровня кодирования
Спасибо, что являетесь частью нашего сообщества! Нанимайте лучших инженеров-программистов на Платформе вакансий Level Up.
