zacharysarah commented 6 years ago

Kubernetes Doc Sprint Guide

Where: KubeCon EU 2018, Copenhagen, Denmark When: Tuesday, 1 May 2018, 9:30am-1pm CEST Room: Contributor Summit, track 3, B4-M5

You can ask questions or send notifications in Slack during any part of the sprint.

Room	Sprint subject	Description
K8s contributor summit	Site migration, good first issues	Smoke test the site migration to Hugo

Facilitators

Name	GitHub username	Role
Zach Corleissen	@zacharysarah	Lead
Jared Bhatti	@jaredbhatti	Lead
Brad Topol	@bradtopol	Facilitator
Ryan McGinnis	@ryanmcginnis	Facilitator

Introduction

Kubernetes is a system for managing containerized application across a series of nodes. It allows applications to be easily deployed and scaled across varied infrastructure components. For more information on Kubernetes, read “An Introduction to Kubernetes” or this quick comic case study, “How many coders does it take to screw in a lightbulb?”.

Doc sprint prerequisites

You don’t need any background on Kubernetes as a product to participate in the doc sprint. However, you do need to:

Have a basic understanding of Markdown
Have an account on Github
Sign the CNCF CLA
Register on the sprint spreadsheet
Join the Kubernetes documentation channel on Slack

If this is your first time submitting a pull request to Kubernetes.io, you’ll need to sign The Cloud Native Computing Foundation's Content License Agreement (CLA). To sign the agreement, you’ll need to register your email with the Linux Foundation. The email you register must match the email address for your GitHub account.

We'll be communicating about sprint progress in Slack, including signaling when PRs are ready for review.

If you need help or have questions about any of these prerequisites, one of the sprint organizers can help.

Kubernetes docs: how do they work?

Locations

Kubernetes documentation is located at kubernetes.io/docs. The GitHub repository for documentation is located at https://github.com/kubernetes/website.

Structure

Documentation exists in four main sections:

Section	Description	Example	Directory
Concepts	Help the user gain deeper understanding of your product ("What is X?", "How does X Work?").	labels and selectors	/docs/concepts/
Tasks	Show a user how to accomplish a specific task, and optionally, different interfaces for doing that task. ("How to do X").	define environment variables	/docs/tasks/
Tutorials	Walk a user through a real-world, industry-specific, or end-to-end development scenario that uses your product. ("How to do Y in the context of ABC").	running Zookeeper	/docs/tutorials/
Reference	Give the user the tools they need to use the product's interface(s).	kubectl overview	/docs/reference/

Style guide

The Kubernetes style guide provides answers to questions about format.

Doc sprint goals

This goal of this doc sprint is to smoke test the k8s.io migration from Jekyll to Hugo.

"Where there's smoke, there's fire."

A smoke test is a non-automated test performed by humans: users crawl through a site looking for anything unusual ("smoke") that could indicate larger problems ("a fire").

Kubernetes.io is migrating from Jekyll to Hugo as its static site generator. Today we'll be testing a "rough cut" of the new site. We want to make sure there aren't any issues with the site before we cut traffic over to the Hugo framework. We need your help to make sure all of our docs functionality, links, and navigation work on our new site.

We'll need your help to:

Review documentation formatting, links, and includes between the new site and the old site.
Open issues against the site that we can fix before cutting over.

Smoke testing the site migration

Navigate to https://hugo-migration.docs.kubernetes.io/.
Open various pages in the Documentation section.
Note whether the page loads correctly, or whether it displays any unusual behavior: odd formatting, stray syntax, or HTTP 404 errors.
If you're uncertain of the behavior, you can open the page on the current live site (https://kubernetes.io) and compare.

Pages of especial interest:

Reference (API, kubectl, kubeadm, kubefed)
Glossary
Contributor guidelines

Creating an issue

Create a new issue in the kubernetes/website repository.
Add the line Hugo Doc Sprint to the Title of the issue and the URL with the issue.
Describe the issue that you found: the more detail, the better.

Prizes!

It isn’t a doc sprint if there isn’t swag. ✨ 🎉 ✨

All participants get their choice of one item of swag from the Kubernetes store. Be sure to enter your choice of swag on the sprint spreadsheet.

Continuing to contribute

If you’re interested in continuing to improve Kubernetes documentation:

Join the Kubernetes SIG Docs Google group
Attend the next Kubernetes docs community meeting (Tuesdays @ 10:30am, PST)