-
Notifications
You must be signed in to change notification settings - Fork 752
Sprinter's Guide
Welcome to the Kubeflow Doc Sprint! This is the guide for people participating in the doc sprint.
Complete the doc sprint registration form if you haven't already done so.
Use Kubeflow v1.0 RC.
For samples and testing of docs, use the latest release candidate for Kubeflow v1.0.
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.
The Kubeflow website, kubeflow.org, describes the Kubeflow components and how to use them. The Kubeflow source code is on github.com/kubeflow.
During the doc sprint, you'll update the documentation that's published on the website at kubeflow.org/docs. The source files for the documentation are on github.com/kubeflow/website.
You may also update the code samples that form the basis of the tutorials. The code samples are on github.com/kubeflow/examples and github.com/kubeflow/pipelines/samples.
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. :) )
-
The docs are written in Markdown (a lightweight markup language). Read a bit about Markdown and GitHub-flavored Markdown, and have a cheatsheet handy.
-
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.
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.
Please do add issues 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.
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.
-
The quick guide to working with a GitHub repo is useful if you who don't often use Git or GitHub.
-
Templates:
-
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.
- Live in the room and over video conference
- In Kubeflow Slack: #doc-sprint
- Comments on issues and PRs
Remember:
- Include remote participants
- Be aware of multiple time zones
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. The tech writing reviewers are:
- joeliedtke
- sarahmaddox
- simmscg
If you have any questions, please contact events@kubeflow.org or ask us in the #doc-sprint channel in the Kubeflow Slack workspace.
Add your work to this doc, for mentioning during the sprint demos session: https://bit.ly/2w30gYT
Complete the doc sprint registration form.
Yes. You can take part in person at the Google Sunnyvale offices and/or online.
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.
Yes please! Tweet #KubeflowDocSprint and talk about the doc sprint on any other channel you like.