Fixing Kubernetes Documentation

John Mulhausen, Lead Technical Writer, Googlejohndylan@google.com / @johndmulhausen on GitHub

The TL;DRThe docs have been… not great.The docs were created by engineers with other problems.Now, Kubernetes has a technical writer (me)This technical writer wants to pay you bounties for helping

with the docsWe’re getting a much-improved new site and a new docs

authoring process… NOW!

New repo: kubernetes/kubernetes.github.io

Let’s compare the old site and the new siteOld site: http://kubernetes.io (for now)

Docs change process: install go and run a battery of munge scripts to validate that they work. Submit PR to a battery of CI integrations which eventually branch your doc from head/release them. Meanwhile the site itself is unstageable.

New site: http://kubernetes.github.io (for now)Docs change process: Hit the blue pencil and write

stuffSo easy even a caveman can do it

Bounty programKubernetes bounties: “Get small amounts for small

contributions to the existing docs”Payment is credit for Google Cloud Platform.Bigger projects like canonical tutorials, we are still

contemplating, but I have budget and would love proposals -- File a bug and cc @johndmulhausen on GitHub

Search the new repo’s issues for “label:bounty”Reference the #issuenumber of the bounty in your PR

Anatomy of new siteNew site is a pure GitHub Pages project reliant on no munging scripts.

Stages the same on your username.github.io fork as on your laptop or in production

GitHub Pages projects run Jekyll, an open-source (Ruby) static site generator

Docs are edited in Markdown (can use HTML inline if needed)

Left-navigation tree, data in general is edited in YAML files

Liquid templating langauge for logic like for loops across YAML, if/then, include files, etc

JavaScript: jQuery is on every page, feel free to use it

CSS: Built from SASS partials

Rouge for syntax highlighting

master branch = current/stable K8s version (currently: 1.2); canonical URLs

Edit in the cloudYou don’t need to install anything to edit the docs.I’ll visit my fork: http://johndmulhausen.github.ioEdit w/blue pencil on your staged fork, or root around in

your fork on GitHubNote: GitHub just got drag-and-drop file uploading!

http://johndmulhausen.github.io updates w/changes automatically

Send PR when doneNote: You can also click the blue pencil on the live site and

it’ll auto-walk you through the fork process.

Edit locallyGet setup (need Ruby 2.2+):

gem install github-pages

git clone https://github.com/kubernetes/kubernetes.github.io.git k8sdocs

jekyll serve k8sdocs

Make changes, see results instantly on http://localhost:4000

Send PR when done

Review processIt’s labels, basically

See: https://github.com/kubernetes/kubernetes.github.io/pulls

If I need a Kubernetes author/expert to validate what your PR is saying, I’ll mark it “Needs Tech Review”

If I have comments that need addressing, I’ll mark it “Docs Review: Open Issues”

When I’m satisfied, “Docs Review: LGTM”

When the Kubernetes author/expert is satisfied: “Tech Review: LGTM”

When all green, in you go.

If you don’t need tech review, I’m gonna wave you in.

Diagram MakingOur current highest-paying bounty. Issue #84

You don’t need to install anything to make diagrams.

Use the “Diagram Asset” slide deck:https://docs.google.com/presentation/d/13klSkUQI9yPxKckP8UFLpzzKzxYwv1lit9ELWOnXJFM/edit#slide=id.p15

Copy/paste results into Google Drawing

Move diagram to top-left

Crop by resizing canvas (from the bottom-right)

File > Download As > SVG

Other Common TasksEdit the left-nav: Hit up the /_data folder and edit the YAML. Example.

Auto-generated Table of Contents (based off of in-page headers). Example.* TOC{:toc}

Present a codeblock: Surround in triple-tics with a Rouge lexer (list). Example.```jsonfoo: “bar”```

Present code from another file. Example.{% include code.html language="<LEXERVALUE>" file="<RELATIVEPATH>" ghlink="<PATHFROMROOT>" %}

Global Variablespage.githubbranch: Associated Kubernetes GitHub repo branch e.g. release-1.2

page.version: Associated Kubernetes version. e.g. v1.2

page.docsbranch: Current GitHub branch on the Docs/Website repo. e.g. release-1.1 or master

Example: http://releases.k8s.io/{{page.githubbranch}}/cluster/addons/README.md

Produces:http://releases.k8s.io/release-1.2/cluster/addons/README.md

In ConclusionThe move is away from everything being all part of the big

Kubernetes repo that does everything.

New repo is a pain, I know, but it’s not the end. It’s a beginning.

We’re hope that we’re making it super easy for our amazing community to jump in.

Of all the ways you can contribute to Kubernetes, I bet you anything you’ll like contributing to the docs best. Not that I’m biased or anything.

Much easier to actually do

Results are immediate

It’s way easier to get PRs past me than it is the Kubernetes authors

I’ve always found that my quest to teach others helps me learn

We’re hiring!

Thank You!GitHub: @johndmulhausen

Slack: @johndylan

Repo: /kubernetes/kubernetes.github.io

Bounties: is:open label:Bounty