Современные реалии таковы, что не каждый бизнес может себе позволить сайт, особенно стартующий бизнес. Поэтому выгодно воспользоваться конструктором сайтов, например filandor. Запуск сайта через несколько минут.
Документы как код — это подход к написанию и публикации документации с использованием тех же инструментов и процессов, которые разработчики используют для создания кода. Эта философия стала более популярной в последние годы, особенно в технологических компаниях. Автоматическая проверка ссылок является частью этого процесса, который гарантирует, что изменения автора являются надежными и безопасными для развертывания. Подготовив почву с помощью подхода «документы как код», технические писатели могут сосредоточиться на том, что у них получается лучше всего: убедиться, что наши читатели получают полезную и точную информацию, которую легко найти, а наша документация говорит на одном языке.
Помимо следования подходу «документы как код», в Cloudflare мы обрабатываем изменения нашей документации публично, в нашем cloudflare-docs Репозиторий GitHub. То, что наша документация открыта для внешних участников, помогло нам улучшить нашу документацию с течением времени — наше сообщество отлично находит проблемы! Хотя нам необходимо просмотреть эти материалы и убедиться, что они соответствуют нашему руководству по стилю и стратегии в отношении контента, вклад, предоставленный сообществом Cloudflare, сыграл важную роль в улучшении нашей документации с каждым днем. В то время как Cloudflare помогает сделать Интернет лучше, наше сообщество помогает создавать лучшую документацию.
Документы как код в Cloudflare
В Cloudflare мы используем подход «документы как код» для создания и публикации документации по продукту в Документах разработчика.
Такой подход включает в себя различные компоненты. Мы используем Git с общедоступным репозиторием GitHub, чтобы отслеживать изменения и обрабатывать ветвление и слияние. Мы полагаемся на GitHub Actions и Cloudflare Pages для непрерывной интеграции и доставки (CI/CD). Наш конвейер непрерывной интеграции проверяет, успешно ли создается документация и есть ли неработающие ссылки. Пользователи, как внутренние, так и внешние, могут просматривать изменения в каждом запросе на вытягивание, а это означает, что соавторам не нужно настраивать локальные среды для предварительного просмотра предлагаемых ими изменений. Однако при желании пользователи могут настроить локальную среду с помощью инструментов с открытым исходным кодом и создать локальные сборки документации.
Следование этой стратегии «документы как код» имеет несколько преимуществ. Мы используем хорошо известные рабочие процессы, которые технические специалисты используют ежедневно. Это упрощает получение отзывов от инженеров, но в то же время достаточно просто, чтобы получать предложения от менее склонных к технологиям людей в компании и от общего сообщества Cloudflare. После просмотра и утверждения вклада в документацию мы можем развернуть эти изменения на сайте активной документации одним нажатием кнопки. Благодаря недавним изменениям в нашем механизме документации, как развертывание, так и локальные сборки выполняются быстро, что помогает увеличить скорость работы нашей команды. Кроме того, можно безопасно реструктурировать части документации, не опасаясь поломки — наш конвейер CI/CD гарантирует, что у нас не будет неработающих ссылок.
Наш подход с открытым исходным кодом
Внутри можно использовать подход «документы как код», используя приватные репозитории. Однако мы не будем распространять некоторые преимущества этого подхода на вклад, предоставленный более широким сообществом Cloudflare.
Как технический писатель в Cloudflare, большая часть работы, связанной с документацией, заключается в том, что она выполняется в нашем общедоступном репозитории GitHub. Я могу отправить изменения в cloudflare-docs Репозиторий GitHub с новой или обновленной документацией, которую затем просматривают мои заинтересованные стороны Cloudflare, такие как менеджеры по продуктам и инженеры.
Помимо этой работы, выполняемой вместе с другими сотрудниками Cloudflare, я также могу решать проблемы и просматривать запросы на вытягивание от внешних заинтересованных сторон, поскольку наша документация имеет открытый исходный код. Например, запрос на вытягивание № 4601 от внешнего участника исправил выражение, которое было неверным в документации:
Благодаря этому вкладу мы смогли выявить множество проблем не только в документации, но и в наших продуктах!
Мы обрабатываем эти дополнения как часть поддержки нашего собственного продукта документации с его собственными ошибками и запросами функций. Проблемы и запросы на вытягивание назначаются, приоритизируются, обрабатываются и проверяются точно так же, как внутренние заявки, даже если они не все находятся в одном и том же невыполненной работе.
Наша работа одинакова как для внутреннего, так и для внешнего вклада. Мы рассматриваем предлагаемые изменения, чтобы убедиться, что новый или обновленный контент соответствует нашему руководству по стилю и нашей стратегии в отношении контента. При необходимости мы запрашиваем техническую проверку содержания. Наконец, мы объединяем изменения, когда они одобрены.
Для вопросов, не связанных с документацией, у нас есть механизм обратной связи на каждой странице документации, который позволяет читателям оставить отзыв о самом продукте. Затем эта информация проверяется внутри компании и обрабатывается соответствующей командой.
Для получения дополнительной информации о том, как вы можете внести свой вклад в документацию, создав задачу или запрос на вытягивание, обратитесь к странице «Участие в документации Cloudflare» в нашем общедоступном репозитории GitHub.
Хранение некоторых секретов
Для контента, который мы пока не можем раскрывать, у нас в настоящее время есть несколько подходов, в зависимости от конкретного технического писателя и вовлеченных заинтересованных сторон.
В некоторых ситуациях мы работаем над общим документом, где мы получаем и отвечаем на прямые отзывы. Ближе к дате выпуска функции мы создаем соответствующую версию Markdown, которую в нужное время помещаем в общедоступный репозиторий GitHub.
В других случаях мы работаем в частном репозитории Git, получая предварительную обратную связь, используя те же процессы, что и для нашего общедоступного репозитория. Этот метод обработки непубличного контента легко реализовать, поскольку мы уже используем подход «документы как код». В этом случае отправка контента на GitHub является простой операцией, когда придет время — это просто вопрос отправки ветки на другой удаленный сервер и создания общедоступного запроса на включение.
Что дальше
Большая часть нашей работы уже сделана публично, но мы все еще можем ее улучшить. Хотя мы предоставляем шаблоны для создания задач и рекомендации по запросам на вытягивание, в конечном итоге мы опубликуем наше руководство по стилю и стратегию контента. Это позволит пользователям заранее знать, что мы будем проверять (и обеспечивать) для каждого вклада в общедоступную документацию, делая наш процесс проверки более прозрачным.
