Skip to content

Sprinter's Guide

Sarah Maddox edited this page Jul 12, 2019 · 10 revisions

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.

About Kubeflow

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.

About the docs

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.

Prerequisites

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.

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.
  • 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.

Talking to each other

  • 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

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:

  • sarahmaddox
  • joeliedtke
  • thedriftofwords
  • alecglassford
  • ccarpentiere (Wednesday only)

If you have any questions, please contact events@kubeflow.org or ask us in the #doc-sprint channel in the Kubeflow Slack workspace.

Sprint demos

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.

You can’t perform that action at this time.