Cadasta's Documentation System

Cadasta utilizes GitBook to generate its online documentation. Note that this is no longer the same as using the GitBook Version 2 service, which (at time of writing) no longer supports multi-language books or exporting books to PDF.^[0]

Information about the inner-workings of GitBook can be found in the GitBook Toolchain Documentation. Useful sections include:

• Support for multiple languages
• Generating eBooks and PDFs

File Layout

The layout of Cadasta's documentation differs slighhtly from the standard GitBook layout. All content is located in the src directory. Key files are:

• src/index.md: The preface / introduction for our documentation (traditionally, this is named README.md).
• src/toc.md: The table of contents for our documentation (traditionally, this is named SUMMARY.md, see Gitbook's Pages documentation for more information).
• src/glossary.md: The preface / introduction for our documentation (traditionally, this is named README.md, see Gitbook's Glossary documentation for more information).

Editing

All documentation content is written in Markdown and can be edited in any standard text editor or the GitBook Editor.

All documentation content is stored in GitHub. Regardless of method, to make changes to Cadasta documentation you must have a GitHub account.

GitBook Editor

The GitBook Editor simplifies the process of editing content if you are not familiar with Markdown.

Read more about setting up GitBook here.

Deploying Changes

Being that this content is all managed via Git/GitHub, we follow standard best practices with code management:

1. Changes should be make in a separate branch. GitBook makes it easy to work in a separate branch via its branch controls in the top-left corner.
2. When you feel that your changes are ready to be deployed, make a Pull Request. If you are unfamiliar with this process, contact a team-member for support.
3. A teammate will code-review your changes for grammar and style and, upon acceptance, merge the changes into the master branch.
4. Changes to the master branch will trigger an automatic build process, deploying your changes within a few minutes.