Skip to content

Focus areas and goals

Jump to bottom
Sarah Maddox edited this page Feb 11, 2020 · 12 revisions

This page gives details of the focus areas and goals for the Kubeflow Doc Sprint, and what you'll get out of attending.

Focus areas

We'll refine our goals together in the doc-sprint Kanban board before and during the sprint.

The primary goals of the doc sprint are:

  • Describe Kubeflow use cases. A November analytics study showed that people visited the use cases section of the docs often. People want to know the most common ways of using Kubeflow, and they need to move on from the getting-started guides to indepth tutorials. But the doc ratings showed that people were disappointed with what they found in the use cases section. We need to fill the gaps. See issue #1596 for further details.

  • Build more end-to-end tutorials: In a UX study in October, Kubeflow users identified documentation as a top adoption driver, and chose end-to-end tutorials as the area that needs most attention. We ran a docs survey in January to get more info.

    Feedback from the January docs survey gives us some good tasks to work on:

    • Many respondents in the January docs survey found that the code samples are out of date or that they cause errors and thus cannot be completed. Yet, most users (54.5%) said that they think the most valuable type of docs are code samples with related tutorials. (Next most valuable were installation/config guides at 27.3%.) So, a very good exercise for the doc sprint is to choose an existing tutorial and test it, then update the code and docs accordingly. (Note that some Kubeflow examples have a related doc while others exist only in the kubeflow/samples repository. Both types are good candidates for the doc sprint.)
    • The survey results show that the most helpful type of tutorial is "end-to-end training and serving of a particular model type (for example, image recognition / NLP / recommendation)" (36.4%). For the doc sprint, you can either develop and document a new sample for a model type, or test an existing sample and document it accordingly.
    • From the survey results, the second-most helpful type of tutorial is "end-to-end deployment of Kubeflow on a particular platform (for example, AWS / GCP / local machine)" (27.3%). So a good exercise for the doc sprint is to choose an existing deployment guide and test it, then update the code and docs accordingly. In particular, on-premises and desktop/server guides need testing and fixing.
    • From the survey results, another helpful type of tutorial is "end-to-end experimentation in a notebook, then moving to K8s for production" (13/6%). We've heard from users in the survey and in other forums that this is a gap that needs filling.

    If you choose one of the above tasks: Check the Kanban board to see if there's already an issue raised for your chosen tutorial. If not, raise one. Assign the issue to yourself (or comment on the issue that you'll take it.)

  • Create trouble-shooting guides for those tricky issues that require the attention of an expert. By bringing many of the community members together during the doc sprint, we'll have those experts on tap!

  • Fix bugs. We're creating a hot list of bugs to fix during the doc sprint. If you spot a bug in the docs, log an issue! Include a comment that you think this is a good candidate for the doc sprint. Assign it to yourself if you'd like to tackle it.

A classification of some of the tasks

Sometimes it helps to put tasks in buckets. So here's a classification of some of the tasks to tackle during the doc sprint:

FAQ

  • Can the tutorial be in a Jupyter notebook? Yes! We'll add a doc introducing the notebook and telling people how to run the notebook on Kubeflow.
  • Where will we put the tutorials and other docs? The main location is on www.kubeflow.org.

What will you get out of it?

Camaraderie and...

  • Wear it with pride: A designer, limited-edition, Kubeflow Doc Sprint T-shirt.
  • See your name in lights: The Kubeflow docs and samples are on GitHub. Your username will appear as author of your contributions.
  • Be part of something big: We'll write up our results on the Kubeflow blog.
  • Talk to Kubeflow community members: A doc sprint is a great way of bringing the community together, in the same room and online.
  • Learn while you sprint: We're planning some lightning talks from UX researchers to help us shine up the way people experience Kubeflow. Technical writers will present tips on writing effectively. You'll also be able to tap the knowledge of the members of the Kubeflow community who'll be sprinting with you.
  • Help other people use Kubeflow: We know Kubeflow is great, and we know how to use it. Help other people know too.

How can you take part?

There are many ways you can take part in the doc sprint:

  • Join us on site for one, two or three days, or participate online. You can mix and match, part on site and part online. (We'll include the online conference details in the calendar invitations.) The on-site doc sprint offers the best experience, as you can chat to the other participants in person, attend the mini learning sessions, and get the most out of having the experts in one room at the same time.
  • Write docs and fix doc bugs.
  • Review pull requests (PRs) containing docs and code written by others.
  • Act as an on-call expert for one or more areas of Kubeflow, to advise people when they're building the tutorials and fixing the docs.
  • Take part in the sprint demos, to show all participants what you've achieved and to cheer others on.

Ready to sign up?

Check out the details and find the signup link at the main page for the Kubeflow Doc Sprint.

Clone this wiki locally