Руководство по содержанию документации

Эта страница содержит рекомендации по добавлению контента в документацию Kubernetes. Если у вас есть вопросы по поводу допустимого контента, обратитесь к каналу #sig-docs в Slack Kubernetes и задайте свои вопросы! Поступайте на своё усмотрение и не стесняйтесь вносить изменения в этот документ через пулреквест.

Для получения дополнительной информации о создании нового контента для документации Kubernetes следуйте инструкциям в руководстве по оформлению.

Участие в контенте

Документация Kubernetes включает содержимое из оригинального репозитория kubernetes/website. Документация Kubernetes находится в директории kubernetes/website/content/<language_code>/docs, большая часть которой относится к проекту Kubernetes. Документация Kubernetes может также включать содержимое их проектов в GitHub-организациях kubernetes и kubernetes-sigs, если у этих проектов нет собственной документации. Всегда можно ссылаться на действующие проекты kubernetes, kubernetes-sigs и (CNCF) в документации Kubernetes, но перелинковка с продуктами определённого разработчика не допускается. Проверьте списки проектов CNCF (Graduated/Incubating, Sandbox, Archived), если вы не уверены в статусе CNCF проекта

Контент, полученный из двух источников

Документация Kubernetes не содержит дублированный контент, полученный из разных мест (так называемый контент из двух источников). Контент из двух источников требует дублирования работы со стороны мейнтейнеров проекта и к тому же быстро теряет актуальность. Перед добавлением контента, задайте себе вопрос:

  • Новая информация относится к действующему проекту CNCF или проекту в организациях на GitHub kubernetes или kubernetes-sigs?
    • Если да, то:
      • У этого проекта есть собственная документация?
        • если да, то укажите ссылку на документацию проекта в документации Kubernetes.
        • если нет, добавьте информацию в репозиторий проекта (если это возможно), а затем укажите ссылку на неё в документации Kubernetes.
    • Если нет, то:
      • Остановитесь!
        • Добавление информации о продуктах от других разработчиков не допускается.
        • Не разрешено ссылаться на документацию и сайты сторонних разработчиков.

Разрешенная и запрещённая информация

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

  1. Инструкции по установке или эксплуатации Kubernetes, которые не связаны с проектами Kubernetes.

    • Разрешено:
      • Ссылаться на документацию CNCF-проекта или на проект в GitHub-организациях kubernetes или kubernetes-sigs.
        • Пример: для установки Kubernetes в процессе обучения нужно обязательно установить и настроить minikube, а также сослаться на соответствующую документацию minikube.
      • Добавление инструкций для проектов в организации kubernetes или kubernetes-sigs, если по ним нет инструкций.
        • Пример: добавление инструкций по установке и решению неполадок kubeadm.
    • Запрещено:
      • Добавление информации, которая дублирует документацию в другом репозитории.
        • Примеры:
          • Добавление инструкций по установке и настройке minikube; Minikube имеет собственную документацию, которая включают эти инструкции.
          • Добавление инструкций по установке Docker, CRI-O, containerd и других окружений для выполнения контейнеров в разных операционных системах.
          • Добавление инструкций по установке Kubernetes в промышленных окружениях, используя разные проекты:
            • Kubernetes Rebar Integrated Bootstrap (KRIB) — это проект стороннего разработчика, поэтому всё содержимое находится в репозитории разработчика.
            • У проекта Kubernetes Operations (kops) есть инструкции по установке и руководства в GitHub-репозитории.
            • У проекта Kubespray есть собственная документация.
      • Добавление руководства, в котором объясняется, как выполнить задачу с использованием продукта определенного разработчика или проекта с открытым исходным кодом, не являющиеся CNCF-проектами или проектом в GitHub-организациях kubernetes, или kubernetes-sigs.
      • Добавление руководства по использованию CNCF-проекта или проекта в GitHub-организациях kubernetes или kubernetes-sigs, если у проекта есть собственная документация.

  2. Подробное описание технических аспектов по использованию стороннего проекта (не Kubernetes) или как этот проект разработан.

    Добавление такого типа информации в документацию Kubernetes не допускается.

  3. Информация стороннему проекту.

    • Разрешено:
      • Добавление краткого введения о CNCF-проекте или проекте в GitHub-организациях kubernetes или kubernetes-sigs; этот абзац может содержать ссылки на проект.
    • Запрещено:
      • Добавление информации по продукту определённого разработчика.
      • Добавление информации по проекту с открытым исходным кодом, который не является CNCF-проектом или проектом в GitHub-организациях kubernetes или kubernetes-sigs.
      • Добавление информации, дублирующего документацию из другого проекта, независимо от оригинального репозитория.
        • Пример: добавление документации для проекта Kubernetes in Docker (KinD) в документацию Kubernetes.

  4. Только ссылки на сторонний проект.

    • Разрешено:
      • Ссылаться на проекты в GitHub-организациях kubernetes и kubernetes-sigs.
        • Пример: добавление ссылок на документацию проекта Kubernetes in Docker (KinD), который находится в GitHub-организации kubernetes-sigs.
      • Добавление ссылок на действующие CNCF-проекты.
        • Пример: добавление ссылок на документацию проекта Prometheus; Prometheus — это действующий проект CNCF.
    • Запрещено:
      • Ссылаться на продукты стороннего разработчика.
      • Ссылаться на прекращенные проекты CNCF.
      • Ссылаться на недействующие проекты в организациях GitHub в kubernetes и kubernetes-sigs.
      • Ссылаться на проекты с открытым исходным кодом, которые не являются проектами CNCF или не находятся в организациях GitHub kubernetes, или kubernetes-sigs.

  5. Содержание учебных курсов.

    • Разрешено:
    • Запрещено:
      • Ссылаться на учебные онлайн-курсы, не относящиеся к CNCF, Linux Foundation или Linux Academy; документация Kubernetes не содержит ссылок на сторонний контент.
        • Пример: добавление ссылок на учебные руководства или курсы Kubernetes на Medium, KodeKloud, Udacity, Coursera, learnk8s и т.д.
      • Ссылаться на руководства определённых разработчиков вне зависимости от обучающей организации.

Если у вас есть вопросы по поводу допустимого контента, присоединяйтесь к каналу #sig-docs в Slack Kubernetes!

Что дальше

Изменено March 27, 2022 at 1:03 AM PST: content-guide_fix (6319b586d6)