Є два офіційні блоги Kubernetes, а CNCF має власний блог, де ви також можете писати про Kubernetes. У головному блозі Kubernetes ми (проєкт Kubernetes) радо публікуємо статті з різними поглядами та особливими акцентами, що мають стосунок до Kubernetes.
За кількома винятками для особливих випадків, ми публікуємо лише вміст, який ще ніде не подавався й не публікувався.
Як автор, ви маєте три різні шляхи до публікації.
Проєкт Kubernetes рекомендує такий підхід: запропонуйте свою статтю, звʼязавшись із командою блогу. Це можна зробити в Kubernetes Slack (#sig-docs-blog). Статті, які ви хочете опублікувати лише в блозі учасників, можна також запропонувати безпосередньо SIG ContribEx comms.
Якщо з вашою заявкою не буде проблем, команда блогу / SIG ContribEx обʼєднає вас у пару з:
Коли команда обʼєднує вас у пару з іншим автором, ідея в тому, що ви підтримуєте одне одного, рецензуючи чернетку статті іншого автора. Вам не потрібно бути експертом у темі; більшість читачів статті теж не будуть експертами. Ми, команда блогу Kubernetes, називаємо іншого автора помічником з написання (writing buddy).
Редактор супроводжуватиме вас на шляху від чернетки до публікації. Він або може безпосередньо затвердити вашу статтю для публікації, або організує затвердження.
Докладніше про процес див. Написання статті.
Другий шлях до написання для наших блогів — почати безпосередньо з pull request на GitHub. Насправді команда блогу цього не рекомендує: GitHub дуже зручний для спільної роботи над кодом, але не ідеально підходить для прозових текстів.
Цілком нормально відкрити placeholder pull request лише з порожнім комітом, а потім працювати деінде, перш ніж повернутися до свого placeholder PR.
Як і в рекомендованому шляху, ми спробуємо обʼєднати вас у пару з помічником з написання та редактором блогу. Вони допоможуть вам підготувати статтю до публікації.
Третій шлях призначено для статей блогу про зміни в Kubernetes, повʼязані з випуском. Щоразу, коли відбувається випуск, команда Release Comms бере на себе графік публікацій у блозі. Люди, які додають можливості до випуску або планують інші зміни, про які проєкт має оголосити, можуть домовитися з Release Comms, щоб їхню статтю запланували, написали, відредагували й зрештою опублікували.
У блозі Kubernetes команда блогу зазвичай планує публікацію статей у будні дні (за григоріанським календарем, який використовується у США та інших країнах). Якщо важливо опублікувати статтю у певну дату, яка припадає на вихідні, команда блогу намагається це врахувати.
У розділі Написання статті пояснено, що робити:
draft: true у front matter)Коли бот Prow зіллє ваш PR, стаття буде чернеткою і не буде запланована до публікації. Потім учасник Kubernetes (ви, ваш помічник з написання або хтось із команди блогу) відкриває невеликий подальший PR, який позначає її для публікації. Злиття цього другого PR вивільняє статтю, що доти була чернеткою, і її може бути автоматично опубліковано.
У день, на який заплановано публікацію статті, автоматизація запускає збирання вебсайту, і ваша стаття стає видимою.
Після того як ви запропонуєте статтю, ми заохочуємо вас використовувати HackMD (вебредактор Markdown) або Google Doc, щоб поділитися версією тексту статті, яку можна редагувати. Ваш помічник з написання може прочитати чернетку, а потім або безпосередньо запропонувати зміни, або надати інший відгук. Він також має повідомити вас, якщо ваша чернетка не відповідає настановам щодо блогу.
Водночас ви зазвичай будете його помічником з написання і можете скористатися нашим посібником щодо підтримки його роботи.
Вам слід підписати CLA, якщо ви ще цього не зробили. Найкраще подбати про це якомога раніше; якщо ви пишете в межах своєї роботи, можливо, доведеться погодити це з юридичним відділом роботодавця або з керівником, щоб переконатися, що вам дозволено підписати.
Команда блогу рекомендує використовувати HackMD (вебредактор Markdown) або Google doc, щоб підготувати й поширити початкову версію тексту статті, яку можна редагувати наживо.
Ваш помічник з написання може коментувати та/або давати відгуки на вашу чернетку і перевірятиме (або має перевіряти), чи відповідає вона настановам. Водночас ви будете його помічником з написання і можете скористатися посібником, який пояснює, як підтримувати його роботу.
Однак на цьому етапі не надто переймайтеся точним форматуванням Markdown.
Якщо у вас є зображення, ви можете вставити растрову копію для отримання перших відгуків. Команда блогу може допомогти вам (пізніше) підготувати ілюстрації до остаточної публікації.
Перегляньте формат Markdown наявних дописів блогу в репозиторії вебсайту на GitHub.
Якщо ви ще не знайомі з ними, прочитайте основи участі. Цей розділ сторінки передбачає, що у вас немає локального клону вашого форку і ви працюєте у вебінтерфейсі GitHub. Проте вам потрібно створити віддалений форк репозиторію вебсайту, якщо ви ще цього не зробили.
У репозиторії GitHub натисніть кнопку Create new file. Назвіть файл допису у форматі /content/en/blog/_posts/YYYY/abbreviated-post-title.md, де …/YYYY/… — підтека з дописами за відповідний рік. Якщо до допису потрібно додати зображення, діаграми тощо, створіть теку /content/blog/en/blog/_posts/YYYY/abbreviated-post-title/ з файлом index.md та додатковими файлами для вашого допису.
Скопіюйте наявний вміст з HackMD або Google Docs і вставте його в редактор. Далі в цьому розділі докладніше описано, що має бути в цьому файлі. Назвіть файл відповідно до запропонованого заголовка допису, але не додавайте дату в назву файлу. Рецензенти блогу разом із вами визначать остаточну назву файлу та дату публікації статті.
Коли ви збережете файл, GitHub проведе вас через процес створення pull request.
Ваш помічник з написання може рецензувати подання й працювати з вами над відгуками та остаточними деталями. Редактор блогу затверджує злиття вашого pull request як чернетки, яку ще не заплановано.
Файл Markdown, який ви пишете, має використовувати Hugo front matter у форматі YAML.
Ось приклад:
---
layout: blog
title: "Your Title Here"
draft: true # буде змінено на "date: YYYY-MM-DD" перед публікацією
slug: lowercase-text-for-link-goes-here-no-spaces # необовʼязково
author: >
Author-1 (Affiliation),
Author-2 (Affiliation),
Author-3 (Affiliation)
---
date: XXXX-XX-XXdraft: true у front matter статті)Як найвищий рівень заголовків у статті використовуйте заголовки Markdown другого рівня (##, а не #). Значення title, яке ви задаєте у front matter, стає заголовком першого рівня цієї сторінки.
Дотримуйтеся посібника зі стилю, але з такими винятками:
{{< caution >}}. Це тому, що виноски призначені для читачів документації, а статті блогу — не документація.{{< code_sample >}}, і часто краще (легше підтримувати), якщо вони його не використовуютьДля ілюстрацій, діаграм або графіків за можливості використовуйте shortcode figure. Для доступності слід задати атрибут alt.
Для ілюстрацій і технічних схем намагайтеся використовувати векторну графіку. Команда блогу рекомендує SVG замість растрових (bitmap / піксельних) форматів діаграм, а також SVG замість Mermaid (джерело Mermaid можна зберегти в коментарі). Перевагу SVG над Mermaid пояснює те, що коли супровідники оновлюють Mermaid або змінюють відображення діаграм, вони можуть не мати простого способу звʼязатися з автором оригінальної статті, щоб перевірити, чи зміни прийнятні.
Посібник з діаграм призначено для документації Kubernetes, а не для статей блогу. Узгоджуватися з ним все одно добре, але:
Вимога щодо масштабованих (векторних) зображень ускладнює подання статей для менш досвідчених людей; Kubernetes SIG Docs і далі шукає способи знизити цей поріг. Якщо у вас є ідеї, як знизити барʼєр, зголошуйтеся допомогти.
Для інших зображень (наприклад, фотографій) команда блогу наполегливо рекомендує використовувати атрибути alt. Можна використати порожній атрибут alt, якщо засоби доступності взагалі не мають згадувати зображення, але це рідкісна ситуація.
Коли ви позначаєте pull request як готовий до рецензування, кожне повідомлення коміту має коротко підсумовувати виконану роботу. Перше повідомлення коміту має бути зрозумілим як загальний опис допису в блозі.
Приклади хороших повідомлень комітів:
Приклади поганих повідомлень комітів:
Коли ви вважатимете, що стаття готова до злиття, слід виконати squash комітів у вашому pull request; якщо ви не знаєте, як це зробити, можна попросити допомоги в команди блогу.