EditingDocs

Our user documentation is generated from source in the project repository under docs. When changes to files under docs land in the master branch, they're deployed by our CI, so making edits to pages on the site is as easy as making a Pull Request against master and getting it merged.

There are two ways to edit docs. We'll call them quick and advanced. The quick way is great for quick edits and for newcomers that don't want to set up the development environment. The advanced way lets you also make edits to the layouts and CSS, and allows you to run a local version to see live changes.

The Quick Way

Every page has a link at the bottom that says "Suggest Edits", which takes you to the GitHub edit page for the source file used to generate that page. Assuming you're logged into Github, you can make the edit on that page and then use the Github web interface to automatically create a new branch and submit a PR.

You can also easily get to this edit page from the Github project page by browsing to the file under the docs directory and clicking the pencil icon to the top right of the document.

The Advanced Way

After you clone the project to your workstation, you'll want to make sure you have at least Hugo installed. However, it might be best to set up the entire development environment described in the README.

It would be a good idea to git checkout a new Git branch before you start working.

The main directories relevant to generating the website are docs and www. The docs directory contains Markdown content files for Hugo. The www directory contains the Hugo configuration and theme files.

Technical note: This is not the conventional way to organize a Hugo project, so we use make to set up a proper Hugo project under a build directory from these files. From the project root directory, you can run make www-build to generate and build the Hugo project under ./build/www.

Running make www-dev will run the Hugo server so you can preview the site locally while you make edits to the content or to the theme files. This will give you the address to put in the browser (though it's usually possible to use http://localhost:1313/).

If it's been very long since you started, you may want to rebase against master before you push your commits. After pushing, you'll have to manually open a PR for your branch against master.

Pull Request Approval

When you create the PR, please add the "docs" label so our editorial team can review your changes for basic grammar and style. They may request edits before the PR is approved and merged.