Skip to content

Kubeflow Doc Fixit at Write the Docs AU 2019

Jump to bottom
Sarah Maddox edited this page Nov 14, 2019 · 14 revisions

Are you coming to the Write the Docs Australia 2019 conference on 14-15 November in Sydney? You're invited to join us in a two-hour doc fixit on Thursday afternoon, as part of the conference.

Become a contributor to an open source project, learn a bit about how open source works, and help improve the experience of Kubeflow users. All in just two hours!

During the fixit, you'll add a touch of tech writer shine to the Kubeflow docs. Docs are a super important part of the user experience of any product. Typos and grammatical inconsistencies can spoil that UX. Yet typos and odd syntax creep into any doc set easily. You can help us set things right.

Your friendly doc fixit helpers

The doc fixit hosts are:

What happens at the fixit

Here's how the fixit works:

  • We’ll start with a short introduction to the Kubeflow open source project.

  • We have a spreadsheet with a list of doc bugs that need fixing. The bugs are the type of problem that you can fix without knowing the software that the docs cover: typos, consistency in page structure, capitalization, and so on.

  • Doc fixit participants choose the bugs that they want to fix.

  • The fixit assistants help the participants create GitHub IDs where necessary.

  • Each participant creates an issue in the GitHub issue tracker, describing the bug they're about to fix.

    Why create an issue? It's a widely-used process in open source to create an issue in the project issue tracker. The issue provides a good place for discussion before making the update, and allows the community to track work requested and done. By raising an issue during the doc fixit, you're contributing useful information to the Kubeflow website project, and also learning a bit about open source processes and tools.

  • The participant then updates the relevant doc on GitHub and sends a pull request (PR) for review.

  • The fixit assistants help people sign the contributor licence agreement if necessary. (A bot will prompt them to do this when they send their first PR.)

  • The fixit assistants review the PRs and approve each PR when it's ready.

  • The continuous merge/publish tools on the GitHub project merge the PR and publish the update in the docs.

  • The participant sees their update appear in the docs!

Prerequisites

Here's how you can prepare for the Kubeflow doc fixit:

  • Bring a laptop with WiFi capabilities.
  • If you don't already have a GitHub account, sign up for one. 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 the Google Contributor License Agreement (CLA). 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.
  • It's not mandatory to do any prework, but it will help if you know some Markdown.

How to raise an issue

Follow these steps to raise an issue in GitHub for the page that you've chosen to update:

  1. Sign in to GitHub if you haven't yet done so.

  2. Go to the page that you want to edit on the Kubeflow website.

  3. Click Create documentation issue.

  4. In the first text box, enter an issue title of this format:

    WtD fixit: Readability improvements for <ENTER YOUR PAGE TITLE HERE>

  5. Check that the auto-generated URL in the second text box matches the URL of the page you want to update. If the URL is not correct, change the URL.

  6. In the second text box, below the URL, enter an issue description. You can just copy and paste the text from the Things to fix cell in the spreadsheet of docs to fix.

  7. Click Submit new issue.

  8. Make a note of the issue URL, or just keep the tab open. You need the issue URL later, to associate your pull request (PR) with the issue.

  9. Copy the issue URL into your row in the spreadsheet of docs that need fixing.

How to update the docs

Below is the basic workflow for editing a page using the GitHub user interface (UI). If you prefer to use the command line interface (CLI) or other tools, please do go ahead and use those instead.

Follow these steps to edit a page using the GitHub UI:

  1. Sign in to GitHub if you haven't yet done so.

  2. Go to the page that you want to edit on the Kubeflow website.

  3. Click Edit this page.

  4. If this is the first time you're updating a file in the Kubeflow website repository, a screen opens asking you to fork the repository. A fork is a copy of the repository where you can make your updates before submitting them for review. You only have to do this once:

    • Click Fork this repository.
    • If GitHub asks you Where should we fork website and offers your username as an option, click the link on your username.
    • Wait a few seconds while GitHub makes a copy of the repository at https://github.com/yourusername/website. This copy is your fork of the kubeflow/website repository.

  5. The GitHub editor interface opens for the selected page. Update the content as described in the spreadsheet of docs to fix.

  6. Click Preview changes at the top of the editing area to see the effect of your changes.

  7. If you need to make more changes, click Edit file at the top of the preview area.

  8. When you are ready to submit your changes, scroll down to the Propose file change section at the bottom of the editing area.

    • Enter the following short description of your update. This short description becomes the title of your pull request (PR):

      WtD fixit: Readability improvements for <ENTER YOUR PAGE TITLE HERE>

      If you see a ProTip from GitHub about great commit summaries containing fewer than 50 characters, you can safely ignore the tip.

    • In the second text box (for the extended description), enter the following text, replacing YOUR ISSUE URL with the URL of the issue that you created earlier:

      Fixes YOUR ISSUE URL

  9. Click Propose file change. A new screen appears, offering you the opportunity to open a pull request.

  10. Click Create pull request.

  11. Optionally, edit the pull request title and description.

  12. Make sure Allow edits from maintainers remains checked.

  13. Click Create pull request again. You have now sent a request to the repository maintainers to review your change.

  14. Check the online preview of your changes:

    • Wait for the automated PR workflow to do some checks. When it's ready, you should see a comment like this: deploy/netlify — Deploy preview ready!
    • Click Details to the right of "Deploy preview ready" to see a preview of your updates.

  15. Tell one of the friendly fixit helpers that your change is ready for review.

More guides

Here are some useful guides for updating the docs:

  • The style guide for the Kubeflow docs is a useful reference when you need to know the patterns we follow for capitalization, spelling, and so on.

  • The Kubeflow website README includes 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. Setting up your own doc server is fun, but it's not necessary for small fixes. You and your PR reviewers can preview your changes online before merging them into the repo.
    • 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.

References

Clone this wiki locally