Chef House Style
We recommend that you use the conventions described in this guide when contributing to the Chef reference documentation.
For Chef applications and components, use:
- Chef Automate
- Chef Habitat
- Chef Infra (formerly Chef)
- Chef Infra Client (Use Chef Infra Client up to version 14.x)
- Chef Infra Server (Formerly Chef Server)
- Chef InSpec
Chef does not follow a specific grammar convention. Be clear and consistent as often as possible. Follow the established patterns in the docs.
A tautology, when used as a description for a component, setting,
method, etc. should be avoided. If a string is a tautology, some effort
should be made to make it not so. An example of a tautology is something
like “Create a new user” (a user created is a
new user) or (for a setting named
cidr_block) “The CIDR block for the
Don’t write an FAQ. FAQs turn into a grab bag of issues that a user might have, but they tend to be disorganized and the information in them is hard to find. FAQs are fine in draft documentation when new documentation is written from scratch, but don’t publish them.
Reformat FAQ questions into an issue that a user might have, followed by the steps to resolve the issue. Then add those issues and solutions to the relevant page in the product documentation.
See this post on FAQs from I’d Rather Be Writing for a more in-depth explanation of why FAQs are a bad documentation practice and suggestions for reformatting FAQ text into something more suitable.
We use the fictional company “Fourth Cafe, Inc.” as an example throughout the docs.
Fourth Cafe, Inc. 123579 4th Ave Seattle, WA 98122
Examples in code:
4thcafe.com domain for generic domains and email addresses in the documentation. Use the
progress.com for examples that should refer directly back to the company.
do not reveal personal information in examples, such as the names of real people, real email addresses, or phone numbers.
do not use the names of bands, musicians, or characters from works that are under copyright.
When writing about security, follow the accepted convention and use “Alice” and “Bob”. Following this convention helps readers see that they are reading a topic about security and integrate the Chef information with their existing knowledge.
Here is a list of some example names for you to use (the last names are translations of “Chef”):
- Ares Koch
- Tamira Bucatar
- Dan Gotvach
- Lena Chushi
- Haris Shefu
- Booker Yolisa
- Kala Baavarchee
- Samuel Tagaluto
Example Email Addresses
firstname.lastname@example.org for the Chef Technical Documentation team.
Example Phone Numbers
Never use a real phone number in an example. For a US phone number, use one from the range reserved for examples in fiction, which is (800) 555–0100 through (800) 555–0199.
Use fictional street addresses in examples.
Use these fictional addresses:
2943 Conifer Drive Seattle, WA 98122
1214 Hollow Road Boston, MA 02110
Example IP Addresses
For IPv4 addresses, use one of the addresses provided in RFC 5735 for documentation.
IPv4 address ranges:
For IPv6 addresses, use one of the addresses provided in RFC 3849 range for documentation.
IPv6 address range:
Some Existing Example Patterns
The Chef docs have some useful example patterns of unknown origin.
- Cookbook documentation uses
custom_webas the example cookbook
- Custom resource documentation uses
siteas the example custom resource
- Templates documentation uses
httpdas the template example
- The documentation uses
webserveras an example role in Chef Infra Client and Chef Infra Server documentation,
- These examples often draw on each other.