Skip to main content

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


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

Example Domains

Use the domain for generic domains and email addresses in the documentation. Use the or for examples that should refer directly back to the company.

Example Names

Don’t reveal personal information in examples, such as the names of real people, real email addresses, or phone numbers.

Don’t 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 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:


IPv4 address ranges:

  • (TEST-NET-1)
  • (TEST-NET-2)
  • (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?


Search Results