Overview
People want to write Chef cookbooks, but more importantly they want to use Chef cookbooks. To make cookbooks more useful for people, they need to be documented so people can know how to use them.
Disclaimer: This spec is a living document, it's on a wiki! While you can update it with additional requirements, not everyone will rush out and update their documentation.
This spec doesn't describe how to use Chef. It doesn't describe how to program in Ruby, either.
Scenarios - Just why should someone document their cookbooks?
Richard is a system administrator configuring systems to run an uncommon software repository management system. He wants to write a new Chef cookbook to configure this for him, and make sure other people can understand what he's written.
Cheryl is a programmer looking for an existing set of cookbooks to help her deploy her application. She needs a basic web server, load balancer stack, but she doesn't want to write a whole new cookbook. She just needs to understand some cookbooks written by the community so she can drop them into her configuration.
So What Gets Documented?
A cookbook itself has several components. Cheryl and Richard need to know how to use each one. Recipes are a special component and detailed separately.
- Attributes - Describe the attributes in context. If the name isn't obvious, say what it is for.
- Definitions - List the parameters used, what object type the definition will use (String, Array, etc), and provide an example resource using the definition.
- Libraries - The full power of RDoc can be realized here, as libraries are arbitrary Ruby.
- Files and Templates - Describe the files and templates used in the resources that use them.
Recipes
Recipes can become very complex with interdependencies. We need to know the following about each recipe:
- List of resources the recipe creates.
- Attributes required.
- If other recipes are required, mention them.
- If this recipe needs site-specific configuration, mention it.
- Known issues.
Documentation Markup
Using an easy to implement comment markup tool could output documentation in a human readable form, such as html, textile, markdown and other languages. The output could be imported or hosted via the chef-server web interface.
Such a tool would allow Richard to create his documentation easily without having to think about it. Cheryl could view cookbook documentation while she's managing her app servers from her Chef interface.