Docs Style Guide
The Chef Documentation is online at docs.chef.io. Our documentation is open source and we follow a docs as code methodology. Our workflow is based in GitHub, we write in Markdown, and we use Hugo as our static site generator.
Any community member can make or suggest a documentation change through pull request (PR) or issue in a documentation repository.
Our main repository (repo, for short) for docs.chef.io is called chef-web-docs. This repo contains the files for Chef Infra Client and the Hugo files for our front-end theme, templates, and shortcodes. The Chef documentation is located in:
chef-web-docsrepo contains a
contentdirectory which holds most the Markdown files in the doc set.
static/imagesdirectory stores the image files used in the docs.
config.tomltells Hugo how to build the navigation menus and contains other Hugo settings. do not modify this file.
We try to keep our documentation source as close to the code as possible, which means that our documentation files are distributed across several product repositories.
The easiest way to find the location of the source file is to select the
Edit on GitHub link at the top of every documentation file in your browser.
Edit on GitHub opens the related documentation file in the correct repository.
You can open a change PR directly in the browser by selecting the pen icon in the documentation file–but you will need to add your DCO directly in the commit message.
which is circled in red in this image.
Chef Software requires all contributors to include a Developer Certificate of Origin (DCO) sign-off with their pull request as long as the pull request does not fall under the Obvious Fix rule. This attests that you have the right to submit the work that you are contributing in your pull request.
See this blog post to understand why Chef started using the DCO signoff.
For more information, review our full DCO signoff policy.
A proper DCO sign-off looks like:
Signed-off-by: Tamira Bucatar <firstname.lastname@example.org>
Your commit message should look something like:
propose changes and finish opening your PR.
You can add a DCO signoff to your pull request by adding it to the text of your commit message, or by using the
--signoff option when you make a commit.
If you forget to add a DCO sign-off before submitting a pull request, you can amend your commit from the command line with the Git CLI by entering
git commit --amend --signoff. After that you’ll need to force push your commit to GitHub using the command
git push -f.
Small contributions, such as fixing spelling errors, where the content is small enough to not be considered intellectual property, can be submitted without signing the contribution for the DCO.
Changes that fall under our Obvious Fix policy include:
- Spelling / grammar fixes
- Typo correction, white space and formatting changes
- Comment clean up
- Bug fixes that change default return values or error codes stored in constants
- Adding logging messages or debugging output
- Changes to ‘metadata’ files like Gemfile, .gitignore, build scripts, etc.
To invoke the Obvious Fix rule, simply add
Obvious Fix. to your commit message.
For more information, see our Obvious Fix policy.
We also use Netlify to deploy our documentation and preview pull requests. Netlify generates a preview of <docs.chef.io> when a pull request is made that changes documentation content. Netlify automatically adds a link to the preview build in a pull request comment.
Contact the documentation team if you would like to suggest adding or removing pages.
See our feedback page if you have any questions or comments for the documentation team.
Was this page helpful?