Docs Contributor Technical Guide

This document explains how to set up your computer and work locally as an ODK-X Docs contributor. Local setup 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-X

Read about the project and the community at ODK-X's website.

Get started with the docs by going to the ODK-X Docs GitHub README.

Set up collaboration accounts

ODK-X is a collaborative community. Before diving in as a contributor, set up accounts on our two main collaboration platforms, GitHub and the ODK-X Forum.

Tip

As you are setting up your accounts, keep in mind that it is very helpful (but not required) to use the same (or similar) username on GitHub, and the ODK-X Forum.

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

1. Set up a GitHub account.

   GitHub is a popular code storage and collaboration platform. You will need a GitHub account to contribute to ODK-X documentation or any other ODK-X projects.

   • ODK-X on GitHub

   • ODK-X Docs on GitHub

2. Join the ODK-X Forum

   The ODK-X Forum is the main place for support questions and conversations that affect the whole ODK-X community (users and other stakeholders, as well as contributors).

   If you have a question about how to use any ODK-X software, or want to get connected with the larger ODK-X community, the forum is the best venue for that.

   Tip

   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 or a GitHub issue?

The ODK-X 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 on Github. 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-X application?

• How do I create a form?

• How do I add a specific feature to a form?

• My ODK-X 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 both places, and we will help you wherever you happen to show up.

Initial Setup

Note

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.

1. Find and open a terminal or command line.

   WindowsMacLinux

   Windows versions prior to Windows 10

   Use Windows PowerShell. (Not the DOS Prompt.)

   We recommend using the Windows PowerShell ISE.

   During initial setup (this section of the guide) you will need to Run as Administrator.

   Throughout the rest of the instructions in this guide, follow the instructions labeled PowerShell or Windows.

   Windows 10

   In Windows 10, you have a choice:

   • Use the Powershell (as described above)

   • Use the Windows Subsystem for Linux.

   If you decide to use the Powershell, follow the Powershell or Windows instructions throughout the contributor guides.

   If you decide to use the Linux subsystem, follow the Bash or Windows instructions throughout the contributor guide.

   Note

   Computers with the Windows 10 Home operating system are incapable of installing some of the tools necessary to edit the docs. Other Windows operating systems, such as Windows 10 Enterprise or Pro, can be used to edit the docs.

Understanding terminal commands

When you open the Terminal or PowerShell, you will see a bunch of symbols that include your username and computer name. This is called the prompt. You type commands after the prompt, and hit RETURN or ENTER to run that command.

Everybody's prompt looks different, so we can't make our documentation match what you see. Instead, we use the $ symbol to represent the Bash prompt and the > symbol to represent the PowerShell prompt. The text that follows the $ or > symbol is the command you need to type or copy.

Below the command, there is sometimes output from the command.

bashPowerShell

$ command is here - type this
Output is here. Don't type this.

Not all commands have output, and we don't always include the output in our documentation unless it is relevant. It is a good idea to glance at your own terminals output for unexpected errors.

To make things more clear, the docs will additionally prefix the prompt with a path (showing what directory you are in) whenever that is important.

bashPowerShell

/odk-x/docs/ $ command is here - type this
Output is here. Don't type this.

1. Install git.

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

   LinuxMacWindows

   Use your distribution's package management system to install git on Linux.

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

   LinuxMacWindows

   Use your distribution's package management system to install Git LFS on Linux.

   After initial installation by the package manager, complete the install by running:

   $ git lfs install
   

3. Install Python 3

   Python is a programming language.

   Most of the ODK-X 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.

   LinuxMacWindows

   Use your distribution's package management system to install Python 3.6+ on Linux.

   (For more help, see Installing Python on Linux.)

4. Set up your working directory

   In whatever directory (folder) on your computer where you organize projects, create a new directory for ODK-X, and then navigate to that directory. (We recommend calling this directory odk-x, and the rest of the guide will assume that's what you called it.)

   BashPowerShell

   $ mkdir odk-x
   $ cd odk-x
   /odk-x/ $
   

   For the rest of this guide, we assume you are in the /odk-x/ directory, or a subdirectory of it.

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

   1. Create the virtual environment.

      BashPowerShell

      /odk-x/ $ python3 -m venv odk-xenv
      

   2. Activate the virtual environment.

      BashPowerShell

      /odk-x/ $ source odk-xenv/bin/activate
      (odk-xenv) /odk-x/ $
      

      The (odk-xenv) 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 odk-xenv/scripts/activate.

      Later, to deactivate the virtual environment:

      BashPowerShell

      (odk-xenv) /odk-x/ $ deactivate
      /odk-x/ $
      

6. Fork the ODK-X Docs repository to your own GitHub account.

   A repository (repo) is a store of all the code and text for a project. The ODK-X 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-X Docs, you will create your own fork.

   1. Go to the ODK-X Docs repo on GitHub.

   2. Use the Fork button (top right) to create your own copy.

   3. After the process completes, you'll be looking at your own fork on GitHub.

7. Clone down your copy to your local computer

   1. From your own fork of the repo on GitHub, select the Clone or download button.

   2. Copy the URI from the text box that opens. It will be something like: https://github.com/your-gh-username/docs.git

   3. Use your terminal to clone the repository.

      You should already be in the odk-x directory, with the virtual environment active.

      BashPowershell

      (odk-xenv) /odk-x/ $ git clone https://github.com/your-github-username/docs.git
      .
      .
      .
      (odk-xenv) /odk-x/ $ cd docs
      (odk-xenv) /odk-x/docs/ $
      

      Note

      This will cause your computer to download the entire ODK-X 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:

      • odk-x

        • docs

        • odk-xenv

      The odk-xenv directory stores your virtual environment, and you should not need to open it or directly view its content. Just ignore it.

      The docs directory is your copy of the ODK-X 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-X Docs repository, keep them out of the docs directory.

      You can use the main odk-x directory for any other files you need to work on. (For example, you may want to create a directory called odk-x/forms to hold XLSForm and XForm files.)

8. 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 origin.

   You also need to give the primary ODK-X Docs repo a name, and our convention is to name it upstream.

   BashPowerShell

   (odk-xenv) /odk-x/docs/ $ git remote add upstream https://github.com/odk-x/docs.git
   (odk-xenv) /odk-x/docs/ $ git remote -v
   origin https://github.com/your-github-username/docs.git (fetch)
   origin https://github.com/your-github-username/docs.git (push)
   upstream https://github.com/odk-x/docs.git (fetch)
   upstream https://github.com/odk-x/docs.git (push)
   

   If everything went right, you should see output similar to what is shown above.

9. 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 requirements.txt.

   BashPowerShell

   (odk-xenv) /odk-x/docs/ $ pip install --upgrade pip
   (odk-xenv) /odk-x/docs/ $ pip install -r requirements.txt
   

   The first command upgrades pip itself to the latest version. Then second checks requirements.txt and installs everything listed in it. This will take several moments.

   Note

   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.txt since you originally ran pip install -r requirement.txt. Run the installation again and then retry your build.

10. 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:

    • Atom

    • Sublime

    • VS Code

    • Notepad++ (Windows only)

    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

1. Find an issue to work on.

   Work on ODK-X Docs is planned using the GitHub repository's issue tracker.

   1. Browse the issue tracker and find one you may want to work on.

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

   3. If you decide to work on an issue, ask for it to be assigned to you in a comment.

   4. 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-X Docs contributor is Issue 207 — Line Edits. The issue is very simple:

   1. Find a typo.

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

2. Make sure you are on the main branch

   A branch is a named sequence of changes representing work on the repo. For example, if you were going to work on Issue 207 — Line Edits, you would create a new branch called line-edits to hold that work. When you were done, you would merge those changes back to the main branch, which we call main.

   The first time you clone the docs repo and start working, you will be on the main branch.

   Each time you come back to starting work on a new issue, make sure you are on the main branch before continuing.

   1. Check the current branch with git branch. This will output a list of branches, with a star next to the current one.

      BashPowerShell

      (odk-xenv) /odk-x/docs/ $ git branch
         branch-name
         branch-name
         branch-name
       * main
         branch-name
      

   2. If you are not on main, switch to main with git checkout.

      BashPowerShell

      (odk-xenv) /odk-x/docs/ $  git checkout main
      Switched to branch 'main'
      Your branch is up to date with 'origin/main'.
      

3. 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 main branch. Then, just to be sure, you can use git status to make sure everything is up to date.

   BashPowerShell

   (odk-xenv) /odk-x/docs/ $ git pull upstream main
   (odk-xenv) /odk-x/docs/ $ git status
   On branch main
   Your branch is up to date with 'origin/main'.
   
   nothing to commit, working tree clean
   

4. Create a new branch for your work.

   BashPowerShell

   (odk-xenv) /odk-x/docs/ $ git checkout -b branch-name
   Switched to a new branch 'branch-name'
   

   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:

   • getting-started-guide

   • contributing

   • fix-issue-13

   Bad branch names:

   • getting started guide

   • Getting started guide

   • Getting_started_guide

   • writing-the-getting-started-guide-adammichaelwood-july-2017-draft

5. 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 this directory:

   src

   Files for the pages at https://docs.odk-x.org/

   If you're going to write or edit documentation text, please read:

   • Docs Markup and Syntax Guide

   • Docs Style Guide

   If you're working on code or deployment, please read:

   • Docs Developer Guide.

     Tip

     You can make minor edits to files directly on github. To do this:

     1. Browse to the folder in which the file to be edited is located

     2. Open the file you want to edit

     3. Click the pencil icon at the top right corner in order to edit the file

     4. Make your changes

     5. Scroll to the bottom of the page to commit your changes

     6. Then create a pull request.

     For more info, visit: https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files

6. Local checks

   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.

   BashPowerShell

   (odk-xenv) /odk-x/docs/ $ make check-all
   

   This will send some build 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 spelling_wordlist.txt.

   • 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:word-list::
     
        abc
        def
        exe
        functool
     
     This Is The Page Title
     ======================
     

   When adding new words to spelling_wordlist.txt or the top of a document file, please keep the words in alphabetical order.

7. Build and check

   We use a Python tool called Sphinx to compile all the .rst files into a working website.

   BashPowerShell

   make odkx
   

   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-X Forum.

   Note

   The warning messages will refer to the file name using the temporary directory path tmp1-src or tmp_src. You need to correct the problems in the real source directory (src).

   When you just can't fix the error…

   If you've done your best and asked on the ODK-X Forum, 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…

8. Serve the documentation website locally and view it.

   BashPowerShell

   (odk-xenv) /odk-x/docs/ $ python -m http.server -d build 8000
   Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/)
   

   1. Open your browser and go to http://localhost:8000.

   2. Read through your doc edits in the browser.

   3. Go back to the source files to correct any errors you find.

   4. Go to your terminal, and press CTRL C to shut down the local web server.

   5. Re-run the build and serve steps.

   6. Continue proofreading.

   Once you are reasonably sure your changes are ready…

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

   Note

   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.

   1. Stage the files for commit with git add.

      To stage all changes for commit:

      BashPowerShell

      (odk-xenv) /odk-x/docs/ $ git add -A
      

   2. Commit the staged files with git commit.

      BashPowerShell

      (odk-xenv) /odk-x/docs/ $ git commit -m "Write a commit message here."
      

      Your commit message needs to be wrapped in quote marks. It should, in a sentence or less, explain your work.

10. Push your committed changes to your GitHub repo with git push.

    BashPowerShell

    (odk-xenv) /odk-x/docs/ $ git push origin branch-name
    

    Tip

    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.

11. Issue a pull request from your GitHub repo to the main ODK-X Docs repo.

    A pull request (or PR) is a request from you to the ODK-X Docs maintainers to pull in your changes to the main repo.

    1. Go to the ODK-X Docs repo on GitHub. (Make sure you are logged in.)

    2. Find the message near the top of the page that mentions your recent pushed branches. Select Compare & pull request to start a pull request.

    3. 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 (odk-x/docs).

       • base should be main.

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

    4. 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. (Write closes #123 if the PR completes the work for the issue. If there's still work to do, write addresses #123.)

       • 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 requirements.txt.

       • Details of any difficulties, questions, or concerns that came up while working on this issue.

    5. 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:

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

    2. Work on the files again locally. (Use git branch to make sure you are still in the same working branch.)

    3. Stage and commit your changes locally again (git add -A; git commit -m "Commit message").

    4. Push your commit (git push origin branch-name).

    5. 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-X.

The next time you work

We hope that contributing to ODK-X 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 outlined above.

Here are a few things to keep in mind when you start your next contribution.

1. Return to main with git switch main.

   New work is done on new branches which are started from main. So, before you start a new branch, return to the main branch.

   BashPowerShell

   (odk-xenv) /odk-x/docs/ $ git checkout main
   

2. Pull in changes with git pull upstream main.

   You need to start your new work from the latest version of everyone else's work.

   BashPowerShell

   (odk-xenv) /odk-x/docs/ $ git pull upstream main
   

3. Update the main branch of your online GitHub repository.

   BashPowerShell

   (odk-xenv) /odk-x/docs/ $ git push origin main
   

4. Find a new issue to work on.

5. Start a new branch for your work with git checkout -b branch-name.

Keep improving

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-X Forum.

ODK-X is a community, and we depend on each other's work. Thank you for your contribution to ODK-X Docs and your presence in this community.