-
Notifications
You must be signed in to change notification settings - Fork 780
Sprinter's Guide
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.
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.
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.
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.
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. Details coming closer to the sprint date.
If you have any questions, please contact [email protected] or ask us in the **_#doc-sprint **_channel in the Kubeflow Slack workspace.
Complete the signup form
Yes. You can take part in person at the Google Kirkland 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.