Chef House Style

[edit on GitHub]

We recommend that you use the conventions described in this guide when contributing to the Chef reference documentation.

Official Names

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

Grammar

Chef does not follow a specific grammar convention. Be clear and consistent as often as possible. Follow the established patterns in the docs.

Tautologies

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 VPC.”

Links

Don’t use “click here” in the text of a link. This can confuse the reader about what exactly they’re clicking on, it make pages difficult to read for people who use screen readers, and it’s a bad SEO practice. Instead use descriptive text to explain what the link will take the user to.

For example, don’t use:

Click here for more information about AWS Lambda.

Instead write something like:

See Amazon’s documentation for more information about AWS Lambda.

FAQs

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.

Examples

Example Company

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: admin@4thcafe.com 4thcafe.pem

Example Domains

Use the 4thcafe.com domain for generic domains and email addresses in the documentation. Use the chef.io or progress.com for examples that should refer directly back to the company.

Example Names

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

Use Chef-Docs@progress.com 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.

Example Addresses

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 addresses:

192.0.2.0
198.51.100.0
203.0.113.0

IPv4 address ranges:

192.0.2.0/24 (TEST-NET-1)
198.51.100.0/24 (TEST-NET-2)
203.0.113.0/24 (TEST-NET-3)

For IPv6 addresses, use one of the addresses provided in RFC 3849 range for documentation.

IPv6 address range:

2001:DB8::/32

Some Existing Example Patterns

The Chef docs have some useful example patterns of unknown origin.

Cookbook documentation uses custom_web as the example cookbook
Custom resource documentation uses site as the example custom resource
Templates documentation uses httpd as the template example
The documentation uses webserver as an example role in Chef Infra Client and Chef Infra Server documentation,name: webserver, role[webserver], and role:webserver.
These examples often draw on each other.

Was this page helpful?