Docs Contributor Technical Guide¶
This document explains how to set up your computer and work locally as an ODK Docs contributor. Local set up includes installing some software, and working locally involves:
- writing documentation text or code in a code editor
- using the Terminal (the "Shell" or "Command Line")
We encourage all potential contributors to try to work locally, following this guide.
Before you begin¶
Learn a little about ODK¶
Read about the project and the community at ODK's website.
Get started with the docs by going to the ODK Docs GitHub README.
Set up collaboration accounts¶
This makes it easy for other people to keep track of conversations which sometimes span multiple online platforms.
If you are willing and able to do so, a profile picture in each place is also very helpful. (But it is okay if you are unable or uncomfortable adding a picture.)
Set up a GitHub account.
GitHub is a popular code storage and collaboration platform. You will need a GitHub account to contribute to ODK documentation, or any other ODK projects.
Join the ODK Developer Slack.
Slack is a popular chat platform. The ODK contributor community uses Slack to discuss development, plan work, and generally keep in touch. If you have a question about how to contribute to ODK Docs, or any other ODK project, the ODK Slack is the best place to ask it.
Conversations related to documentation are held in the
#docs-codechannel. You may also want to check in with
- Get an automated invitation from http://slack.getodk.org
- Check your email for the invitation.
- Follow the link in your email and set up your account.
Join the ODK Forum
The ODK Forum is the main place for support questions and conversations that affect the whole ODK community (users and other stake holders, as well as contributors).
If you have a question about how to use any ODK software, or want to get connected with the larger ODK community, the forum is the best venue for that.
The forum has a search feature, and a long history of archived support posts. When writing new documentation about an existing feature, old forum posts are an excellent source for figuring out what people need to know: If someone has asked a question about it, it should probably be in the documentation.
Should I ask in the Forum, the Slack, or a GitHub issue?
The ODK community talks a lot, in a lot of places. Sometimes it's hard to know where to ask a question.
Contribution-related questions and problems should be asked in Slack. This includes things like:
- How do I set up my local editing environment?
- How do I use git?
- I'm having a merge conflict.
- I got an error at the terminal which I don't understand.
- How do I add a picture to a document?
- What issue should I work on?
Work-specific questions and discussion should take place on the GitHub issue defining the work. This includes things like:
- I'm writing a piece of content, but I'm not sure where it should be organized.
- I'd like to work on this feature, but I don't know how to implement it.
- Here's my idea for solving this problem. Is that a good idea?
- I'm going to be working on this for the next few days. No one else should also work on it at the same time.
- I said I was working on this, but I didn't finish and I'm no longer working on it.
User-related questions and problems should be asked in the Forum. (You should use the search feature first, since someone else may have already asked the same question.) This includes things like:
- How do I install an ODK application?
- How do I create a form?
- How do I add a specific feature to a form?
- My ODK application crashed.
But don't worry about posting a question in the wrong place.
It is better to ask a question in the "wrong" venue than to not ask the question at all. Many of the same people are present in all three places, and we will help you wherever you happen to show up.
We generally recommend starting with the Docker platform for editing docs unless you already have a Sphinx environment set up. Local tools and workflows presented in this guide are what the authors feel would be easiest for newcomers and those unfamiliar with open source.
However, developer and authoring tools have a lot of options and alternatives. You should feel free to use your preferred tools.
Before you begin working the first time you will need to install a few tools on your computer.
You should only need to do this one time on any computer.
Find and open a terminal or command line.
Git is a version control system. It helps us keep track of changes to the documentation. (Similar to the undo history in a document editing program.)
Install Git LFS
Git Large File Storage (Git LFS) is a tool that helps us manage images, videos, and other files which are neither text nor code.
Install Python 3
Python is a programming language.
Most of the ODK Docs tools are written in Python, so you need it installed on your computer in order to use those tools. (Don't worry. You don't need to know how to program in Python.)
We require Python 3, version 3.6 or later.
Set up your working directory
In whatever directory (folder) on your computer where you organize projects, create a new directory for ODK, and then navigate to that directory. (We recommend calling this directory
odk, and the rest of the guide will assume that's what you called it.)
For the rest of this guide, we assume you are in the
/odk/directory, or a subdirectory of it.
Set up a virtual environment
A virtual environment is a Python construct that lets you download and install tools for a specific project without installing them for your entire computer.
Create the virtual environment.
Activate the virtual environment.
(odkenv)before the prompt shows that the virtual environment is active. You will need to have this active any time you are working on the docs.
If the file cannot be found, your activate file may be located under odkenv/scripts/activate.
Later, to deactivate the virtual environment:
Fork the ODK Docs repository to your own GitHub account.
A repository (repo) is a store of all the code and text for a project. The ODK Docs repo is kept at GitHub.
On GitHub, a fork is a copy of a repo, cloned from one user to another. In order to work on ODK Docs, you will create your own fork.
- Go to the ODK Docs repo on GitHub.
- Use the Fork button (top right) to create your own copy.
- After the process completes, you'll be looking at your own fork on GitHub.
Clone down your copy to your local computer
From your own fork of the repo on GitHub, select the Clone or download button.
Copy the URI from the text box that opens. It will be something like:
Use your terminal to clone the repository.
You should already be in the
odkdirectory, with the virtual environment active.
This will cause your computer to download the entire ODK Docs repository, including a large number of images. It will take several minutes to complete.
Your local directory
If you followed the instructions, you should now have the following directory structure:
odkenvdirectory stores your virtual environment, and you should not need to open it or directly view its content. Just ignore it.
docsdirectory is your copy of the ODK Docs repo. You will do most of your work in this directory.
If you need to download or create additional files which are not actually a part of the ODK Docs repository, keep them out of the
You can use the main
odkdirectory for any other files you need to work on. (For example, you may want to create a directory called
odk/formsto hold XLSForm and XForm files.)
Set the upstream remote
In git, a remote is a copy of a repo somewhere else. From your local computer's point of view, your online copy at GitHub is a remote.
When you cloned down a repo, your local copy gives your GitHub copy the name
You also need to give the primary ODK Docs repo a name, and our convention is to name it
If everything went right, you should see output similar to what is shown above.
Install Python tools with pip
Pip is a package management tool that comes with Python. We use it to download and install our documentation tools. These Python tools are listed in
The first command upgrades pip itself to the latest version. Then second checks
requirements.txtand installs everything listed in it. This will take several moments.
If you are ever running one of the build commands shown below and it fails with a message that includes
ModuleNotFoundError, there might be changes to
requirements.txtsince you originally ran pip install -r requirement.txt. Run the installation again and then retry your build.
Choose a text/code editor
The documentation source files are written in a plain text format called reStructuredText. This means special formatting (bullets, headers, bold text) is represented by visible characters, not hidden behind a graphical display. When working on a documentation file, you see and write something that looks like:
#. Choose a text/code editor The documentation source files are written in a plain text format called `reStructuredText`_. .. _reStructuredText: http://docutils.sourceforge.net/docs/user/rst/quickref.html
You cannot write and edit these files in a typical document preparation program like MS Word or Google Docs. Instead, you need a coding editor.
There are a lot of editors, and people who use them often have very strong opinions about them. You are free to choose any editor you like.
If you've never used an editor before, you might want to start with one of the easier and more popular ones:
Most of these have plugins that will make writing reStructuredText easier by color-coding the markup.
This completes the setup of your local working environment. Take a break before diving into how you actually work.
Working on the docs¶
Find an issue to work on.
Work on ODK Docs is planned using the GitHub repository's issue tracker.
- Browse the issue tracker and find one you may want to work on.
- Make sure you understand the goal of the project. If the goal isn't clear, ask. If there is anything in the issue that doesn't make sense, ask about it. Feel free to make suggestions about how something could be accomplished.
- If you decide to work on an issue, assign yourself to it by writing @getodk-bot claim in a comment.
- If the issue requires a novel or creative solution not defined in the issue already (we've stated a problem and you think you know a way to fix it) write a comment describing your plan. It is a good idea to get feedback on an idea before working on it. Often, other contributors can provide additional context about why a particular solution may or may not work.
Your first issue
The very first issue you should work on as a new ODK Docs contributor is Issue 96 — Line Edits. The issue is very simple:
- Find a typo.
- Fix the typo.
This will help you get used to working with the documentation tools, and helps us get rid of the inevitable errors that creep in to our writing.
Make sure you are on the master branch
A branch is a named sequence of changes representing work on the repo. For example, if you were going to work on Issue 96 — Line Edits, you would create a new branch called
line-editsto hold that work. When you were done, you would merge those changes back to the main branch, which we call
The first time you clone the docs repo and start working, you will be on the master branch.
Each time you come back to starting work on a new issue, make sure you are on the
masterbranch before continuing.
Check the current branch with git branch. This will output a list of branches, with a star next to the current one.
If you are not on master, switch to master with git checkout.
Pull in changes from upstream
Other people are constantly making changes to the docs, so you need to keep your local copy up to date.
Before you start working, use git pull to pull in the changes from the upstream repository's master branch. Then, just to be sure, you can use git status to make sure everything is up to date.
Create a new branch for your work.
Branch names should be short, lowercase, and use hyphens as separators. They do not need to carry a lot of information (like your name or the date).
Good branch names:
Bad branch names:
getting started guide
Getting started guide
Work on the documentation
Finally, you can open an editor of your choice and work on the documentation.
The source files for documentation text are in these directories:
Files for the pages at https://docs.getodk.org
If you're going to write or edit documentation text, please read:
If you're working on code or deployment, please read:
Once you have worked on the documentation, we want to make sure your contribution will get accepted and published right away.
To ensure your changes will pass all the deployment tests, you should run the tests locally first and correct any problems.
If you've been working on files in
This will send some output to the terminal, which will include mentions of any words not in the dictionary.
If the flagged words are really misspellings, correct them.
If the flagged words are not misspelled, and should be in the dictionary add them to
If the flagged words are not misspelled, but should not be in the dictionary (for example, they are non-words that make sense on a single page for a specific reason) add them at the top of the file in which they are being used, before the title heading:
.. spelling:: abc def exe functool This Is The Page Title ======================
When adding new words to
spelling_wordlist.txtor the top of a document file, please keep the words in alphabetical order.
Build and check
We use a Python tool called Sphinx to compile all the
.rstfiles into a working website.
If you've been working on files in
This generates a lot of output. Near the end of the output you may see a statement like:
build succeeded, 18 warnings.
Those warnings are problems with the text which you need to fix before submitting your changes. Scroll up in the terminal to find each warning, so that you can address it in the source files.
A Sphinx warning looks like this:
/path/to/file-name.rst:LINENUMBER: WARNING: warning message short excerpt from the file
This tells you what file the problem is in, the approximate line number, and the nature of the problem. Usually that is enough to fix it. If you can not figure out the meaning of a particular warning, you can always ask about it on the ODK Slack.
Because of a bug in Sphinx the line numbers in error and warning messages will be off by about 15 lines (the length of
As you fix each warning, run the build again to see if it disappears from the output.
The warning messages will refer to the file name using the temporary directory path
tmp. You need to correct the problems in the real source directory (
When you just can't fix the error…
If you've done your best and asked on the ODK Slack, and you still cannot correct the warning, stop worrying about it and skip to the next step. When you submit your changes on GitHub, include a note about the warning. Other contributors will help solve the problem before merging.
Once you've corrected all the warnings that can be corrected…
Serve the documentation website locally and view it.
If you've been working on files in
- Open your browser and go to http://localhost:8000.
- Read through your doc edits in the browser.
- Go back to the source files to correct any errors you find.
- Go to your terminal, and press
CTRL Cto shut down the local web server.
- Re-run the build and serve steps.
- Continue proofreading.
Once you are reasonably sure your changes are ready…
Commit your changes to your local repository.
A commit is snapshot of your working files in a particular state, along with a record of all the changes that led up to that state. That snapshot is what you will submit to the main repository.
We explain how to do a commit at this step because you need to do it before you can submit your changes. However, you don't have to wait until you are done to commit. You can commit as many times as you like while working.
This can be especially helpful if you are working on a complicated set of changes, over several working sessions.
Stage the files for commit with git add.
To stage all changes for commit:
Commit the staged files with git commit.
Your commit message needs to be wrapped in quote marks. It should, in a sentence or less, explain your work.
Push your committed changes to your GitHub repo with git push.
You may be prompted to enter your GitHub username and password. When entering your password, the cursor won't move — it will look like you aren't entering anything, even though you are.
To avoid having to retype these every time, you can store your GitHub credentials locally.
Issue a pull request from your GitHub repo to the main ODK Docs repo.
A pull request (or PR) is a request from you to the ODK Docs maintainers to pull in your changes to the main repo.
Go to the ODK Docs repo on GitHub. (Make sure you are logged in.)
Find the message near the top of the page that mentions your recent pushed branches. Select Compare & pull request to start a pull request.
Follow GitHub's instructions to start the pull request.
These details should fill-in automatically, but be sure to double-check them:
- Base fork should be the main repo (
- base should be
- Your repo and working branch name should be listed beside them.
You will see either a green Able to be merged message or a message informing that the branch can not be merged. You can proceed in either case. If the branch cannot be merged, the maintainers will work with you to resolve the problem.
- Base fork should be the main repo (
Write a PR message explaining your work.
The PR message field includes a template to remind you of what to include. Fill in the template and delete any sections which are not applicable.
A good PR message includes:
- The issue number you are working on.
closes #123if the PR completes the work for the issue. If there's still work to do, write
- A summary of what you did.
- Details of work that still needs to be done.
- Details of new work created or implied by this PR.
- Details of any unresolved errors or warnings, including details of what you tried.
- Justification for any changes to
- Details of any difficulties, questions, or concerns that came up while working on this issue.
- The issue number you are working on. (Write
Submit your pull request.
The maintainers and other contributors will review your PR as quickly as possible. They may request changes to your work. If changes are needed:
- Don't worry. Revision is a normal part of technical writing, and everyone (even the project's founders and leaders) has their work reviewed and are frequently asked to revise it.
- Work on the files again locally. (Use git branch to make sure you are still in the same working branch.)
- Stage and commit your changes locally again (git add -A; git commit -m "Commit message").
- Push your commit (git push origin branch-name).
- Your new commits will automatically update the PR. Do not start a new PR.
Once everything has been approved, the changes will be merged in and will appear on this website. At that point… congratulations! You are now a contributor to ODK.
The next time you work¶
We hope that contributing to ODK Docs is a rewarding experience and that you'll want to keep going. Each time you start work on a new issue the process is the same as outline above.
Here are a few things to keep in mind when you start your next contribution.
masterwith git checkout master.
New work is done on new branches which are started from master. So, before you start a new branch, return to the master branch.
Pull in changes with git pull upstream master.
You need to start your new work from the latest version of everyone else's work.
Update the master branch of your online GitHub repository.
Find a new issue to work on.
Start a new branch for your work with git checkout -b branch-name.
As you are getting comfortable with the contribution process, take a few minutes to read our Tips for Making Good Contributions. You may also want to dig deeper into the Docs Style Guide and the Docs Markup and Syntax Guide. (And if you are writing code, check out the Docs Developer Guide.)
And don't forget to join us on the ODK Slack.
ODK is a community, and we depend on each other's work. Thank you for your contribution to ODK Docs and your presence in this community.