Skip to content

Kubeflow Doc Fixit at Write the Docs AU 2019

Jump to bottom
Sarah Maddox edited this page Nov 1, 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 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.
  • 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

TODO

How to update the docs

Below is the basic workflow for editing a page using the GitHub user interface (UI):

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

  2. Click Edit this page. The corresponding file opens in the GitHub repository.

    For example, if you want to update this page:

    https://www.kubeflow.org/docs/upgrading/upgrade/

    Then you need to edit this file in the repository:

    https://github.com/kubeflow/website/blob/master/content/docs/upgrading/upgrade.md

  3. Update the content as described in the issue spreadsheet.

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

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

  6. When you are ready to submit your changes, scroll down to the Commit changes section at the bottom of the editing area

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

    • Optionally, enter a longer description in the second text box.

  7. Select the radio button to Create a new branch for this commit and start a pull request.

  8. Optionally, change the branch name. The default branch name is yourusername-patch-1.

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

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

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

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

  13. 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 ad 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