Documentation

We could really use some help telling our story, and we’d love your help.

First, a bit about how our docs are stored and managed. Each MOTECH code repository contains a docs directory populated with reStructured Text (reST) files. These files are built by Sphinx and hosted at http://readthedocs.org. This page contains more information about reStructuredText and how to build the docs on your local machine. Once you’ve written and built your docs locally, you can just check them in and they’ll automatically appear on our docs site after the next doc build.

The instructions below will let you know how to get started with adding/editing MOTECH documentation.

Note

If you are a writer (not a software developer!) and you find that committing documentation to GitHub is a bit daunting, drop us a line. We can provide extra support through the process (or even check in your docs for you).

Mailing Lists and Accounts

  1. Sign up for the MOTECH Developer mailing list - this is the best place to get help with any questions about MOTECH documentation or code.
  2. Create an account on GitHub, our code repository and review system.
  3. Get a Jira account if you’ll be working on documentation tickets - there is no self-serve way to request a Jira account yet, so please just email the MOTECH Developer list and we’ll get you set up.

Doc Environment & Tools

  1. Fork our GitHub repository.
  2. Clone your repository locally and enter the motech/docs directory.
  3. Install an editor for reStructuredText. Any editor will work, but we find that Sublime works pretty well.
  4. Install Sphinx and Javasphinx, and test out building the docs locally. Full instructions here.

Finding Something to Work On

  1. All planned documentation topics for MOTECH are tracked in Jira – you are welcome to pick any unassigned ticket from this query. Note that many of the tickets have sub-tickets as well, so you can drill down to find additional unassigned topics.
  2. If the topic you want to write about doesn’t appear to be tracked in Jira, email the list and let us know. We’ll help you determine where the topic fits in our ToC and create a Jira ticket for it.
  3. Assign the Jira ticket to yourself and click “Start Progress” when you’re ready to start writing.

Writing and Submitting Your Doc

  1. As you are writing your doc, we recommend building periodically to ensure that the doc looks the way you expect. It can take some trial and error to get the hang of reStructuredText markup.
  2. When you’re ready to push your changes, please squash your commits to keep the change history concise, and write a commit message that conforms to our guidelines.
  3. Submit your doc using git push origin - this sends your changes to the MOTECH fork on your GitHub repository.
  4. Now, you have to create a pull request from your GitHub fork to our repository for review. This is easily done through the GitHub user interface.
  5. Please incorporate review feedback and update your pull request as needed - once your change has passed code review, one of the project maintainers will merge your change to the repo.
  6. Resolve the relevant issue(s) in Jira.