This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Cloud Native Computing Foundation (CNCF)
- Technical writer:
- Syam Sundar K
- Project name:
- More and Better Kubectl Examples
- Project length:
- Standard length (3 months)
Project description
The motive of this project would be to enhance the existing kubectl cheat sheet and reference docs.
These are the ultimate goals of this project: • Create more and better kubectl examples. • Add kubectl examples to the kubectl cheat sheet. • Refactor kubectl docs for maximum helpfulness.
Goal I - Examples for kubectl:
Will be working closely with the CLI special interest groups in order to get the context of, what kind of examples that the kubernetes users want the most and documenting it. This can range from improving the existing kubectl commands on the cheat sheet to adding new commands to the cheat sheet.
Goal II - Increased Helpfulness of docs:
In order to increase the helpfulness of the docs, the following can be done:
• Eliminate beginner struggles • Rearranging kubectl command in a certain order to ensure continuity in the logical flow
Eliminate beginner struggles through better command / user-case explanations. This can seem simple but can significantly influence beginners to either continue or drop their learning. Say for an instance, when I got started with kubernetes through kubectl, I wasn’t sure of the differences between pods and deployments. Initially I deployed a backend service written in nodejs. After a few hours, I wanted to bring it down, so I tried deleting the pod, but due to the self-healing nature of the pods they were created again. I was kind of baffled with what was going on and was wondering why it was getting recreated and not getting deleted. After a few lookups on the web I figured out deleting pods is not the same as deleting a deployment. For a trained eye this might seem simple but a clear explanation that eliminates these kinds of ambiguities is what distinguishes a good doc from a great doc.
Rearranging kubectl command in a certain order to ensure continuity in the logical flow. If you are someone like me who is a strong believer of storytelling, you would probably be wondering, how do you bring storytelling elements into a doc sheet that has a list of terminal commands, I say, it can be done. Anything that we learn always has a logical flow to it - a starting and an ending point, if you will. Kubectl as a command line tool, obviously has a learning curve, in fact it’s learning curve coincides with the learning curve of Kubernetes itself. Since almost everyone starts their journey with kubernetes through kubectl (except the folks who use web UI) and since it’s learning curve is tightly coupled with the learning curve of kubernetes, The docs can be made significantly better just by changing the order of these commands and introducing storytelling elements to it. Say for an instance, features like horizontal pod autoscaling can be explained after explaining resources with real world examples and illustrations.
Goal III - Docs Usability Improvements:
Recent migration of Kubernetes website to Docsy Hugo is awesome and is a massive shift in the docs perspective. Although the migration was successful, there is still room for a lot of improvements in the doc space.
Here are some of change that I would suggest,
• Left pane auto scroll to the currently active section on the main docs - This can be helpful in keeping track of the current, upcoming and past sections. • Copy to clipboard - some commands can be lengthy, copy functionality can be helpful while working with these kinds of commands. • Content Formatting of doc files - After migration, the contents in few pages are not formatted in a proper way. eg: Resource Type section in kubectl overview. This degrades the user experience.
These are the changes that can enhance the user experience on the kubernetes website and can also boost user productivity.