Fixing Kubernetes Documentation
John Mulhausen, Lead Technical Writer, [email protected] / @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
Top Related