Welcome to the Kubeflow Doc Sprint! This is the guide for people participating in the doc sprint.
Complete the signup form to register for the doc sprint if you haven't already done so.
What is a doc sprint?
A doc sprint is a hackathon for docs. Over the course of three days, we'll develop tutorials and fix documentation bugs. Sprinters are joining us at the Google office in Kirkland and remotely from all over the world. See the agenda and other details on the main Kubeflow Doc Sprint page.
Kubeflow is an open source machine learning toolkit for Kubernetes. When you install Kubeflow, you get a set of configuration files that define the platforms and services for each stage of the machine learning (ML) workflow, such as data preparation, model training, prediction serving, and service management. You can choose to deploy your ML workloads locally or to a cloud environment. You can adapt the configuration files to suit your environment and the services that you want to use.
About the docs
Before you get started, you need to set up some accounts and get to know some tools. If you have time to do this before the start of the sprint, that's great. If not, you can do it during the sprint:
Sign up for a GitHub account if you don't already have one.
Sign the Google Contributor License Agreement (CLA) and follow the Kubeflow Code of Conduct:
- Head over to https://cla.developers.google.com/ to see your current agreements on file or to sign a new one. If you've already done this for some other project, you shouldn't need to do it again.
- If you haven't signed the CLA by the time you send your first pull request (PR), the automated Googlebot will prompt you to do it.
- Read more about the CLA and the Code of Conduct in the contributor guide.
If you plan to work on tutorials that run Kubeflow on a particular cloud platform, you need to set up an account with that platform. Examples of cloud platforms include Google Cloud Platform (GCP), Amazon Web Services (AWS), IBM Cloud Private, and more. You can see the already-documented guides to setting up specific cloud environments in the Kubeflow getting-started guide. (Note that your task in the doc sprint may be to create such a guide for another platform. :) )
You may find yourself updating text and/or code in a Jupyter notebook. You don't need prior experience with notebooks, but it's good to understand what they are. A Jupyter notebook is an application (web page) that contains text blocks (called text cells) and code cells on the same page. The page is interactive, in that you can run the code cells and see the results displayed on the page. If you have edit rights to the page, you can also update the text and code cells.
- Join the #doc-sprint channel in the Kubeflow Slack workspace, so that you can chat to other sprinters.
What to work on
You'll build new tutorials and/or fix bugs during the doc sprint:
The doc-sprint Kanban board includes issues tagged with the label doc-sprint. The board also includes some note cards that haven't yet been analysed to produce individual issues. We'll do that analysis and discussion during the sprint, or you can feel free to start earlier too.
The tutorial wish list (spreadsheet) is a discussion doc from which many of the above issues are drawn.
Please do add issues or spreadsheet entries in the leadup to the doc sprint. We'll discuss the resulting doc tasks before and during the doc sprint.
For a more philosophical overview of what to work on, see the focus areas and goals of the doc sprint.
How to update the docs
Here are some useful guides to updating the docs:
The Kubeflow website README has a guide to updating the docs, including:
- A quickstart for those who are familiar with GitHub and just want to update a doc page and preview the resulting web page online.
- How to set up your own doc server so that you can preview your changes locally as you type.
- Information about the documentation theme and styles.
- A "quick guide to working with a GitHub repo", for people who don't use git or GitHub often.
For further information about the GitHub workflow, refer to the GitHub guide to pull requests or ask a co-sprinter at the Kubeflow Doc Sprint.
For guidance on writing effective documentation, see the style guide for the Kubeflow docs.
Talking to each other
- Live in the room and over video conference
- In Kubeflow Slack: #doc-sprint
- Comments on issues and PRs
- Include remote participants
- Be aware of multiple time zones
Reviewers and contacts
In general, a reviewer must be a member of the OWNERS file in the relevant repo to be able to approve a change. If you're changing a doc file, the reviewer must be in the kubeflow/website OWNERS file.
During the sprint we'll have tech writers and co-sprinters on hand to help with reviews. Tech writing reviewers include:
- ccarpentiere (Wednesday only)
Add your work to this doc, for mentioning during the sprint demos session: https://bit.ly/30uQ8lE
Quick questions and answers
How do I register to take part in the Kubeflow Doc Sprint?
Complete the signup form
Can I take part remotely?
Yes. You can take part in person at the Google Kirkland offices and/or online.
What if I'm not in the US Pacific Time zone?
Participants are welcome from all time zones. Take a look at the agenda to see if you can join one of the online calls. Even if the call times don't suit you, sign up and let us know you're taking part and we'll make sure you have work to do. Join the #doc-sprint channel in the Kubeflow Slack workspace (invitation to Kubeflow Slack) to chat with other sprinters about your progress and any roadblocks you may encounter.
Can I spread the word about the doc sprint?
Yes please! Tweet #KubeflowDocSprint and talk about the doc sprint on any other channel you like.