Documenting manifests

We as good sysadmins/developers try to postpone documenting until we've got everything in place and working (something that never really happens). Anyway, when we're finally persuaded by our managers we should document our great creation it's always desirable to follow some standard so our documentation is reusable by others (unless we're afraid they're thinking about firing us, what's that sudden interest in documentation?)

Joking apart, having a standard document format for manifests would be great for manifest sharing, and for possibly having a tool that could generate HTML (or other format) documentation in a near or far future, really useful when our manifests begin to grow. Daydreaming includes a graphical tool that would draw nice graphs of our configuration with our documentation attached.

Proposed format

Here you have a first draft of what could be a standard class documentation:

#
# Class name::of::the::class
#  Here you may include a description of the class, its intended uses, and any other
#  thing you think is important.
#
# Incompatible classes
#  * incompatible::class: Why this class is incompatible
#
# Parameters
#  * parameter_name: Description of the parameter, and how it affects the class behavior
#
# Facts
#  * factname: How, why and where you use the fact,  and how it affects the class behavior
#
# Files
#  * path/to/my/file: Description of file (sometimes obvious)
#
# Templates
#  * path/to/my/template: Description of template
#

Rationale

• Description of the class: it's always handy to have a description of the class, so you can take a quick look and know what the class does, how can you use, ...
• Incompatible classes: Sometimes you may have defined classes that are incompatible. For example, you may have a class defining a NTP server and another class defining a NTP client, and you can't apply both classes to the same node. Here you may specify these kind of incompatibilities, so somebody using your manifests doesn't include incompatible classes in some node.
• Parameters: Many times the behavior of a class is affected by some externally defined variable, so we can use that variable to modify the class behavior. Documenting such variables here will make reusing the class easier, so we don't forget to set some variable with the correct value.
• Facts: We also may use facts to alter the behavior of a class. It may be useful to include the facts we're using, so some alteration in the class behavior due to a change in a fact from our nodes doesn't make us crazy.
• Files: Class behavior is greatly achieved using files to properly configure our applications, services, etc. so knowing which files we're using is important.
• Templates: Everything said in files is valid for templates

Where to go

This is just a starting point, feel free to add anything you think it would be useful. Do you think it would be useful to document other parts of the manifest in addition to classes?

About the document format, I don't know anything about RDoc, but in javadoc they use tags with an '@' prepended, so the parser is easier to write. I guess writing a tool to parse this kind of documentation would be related to some extent to the puppet parser.

Actually, I personnally think that a new syntax should not be created, and we should reuse the "javadoc" de-facto standard used by other parsers, like phpdoc, javadoc and, to some extent, Doxygen (which uses the backslash instead of @, but also supports the javadoc syntax anyways). Let's not reinvent the wheel here. -- TheAnarcat

I'm with TheAnarcat here. Let's not reinvent the wheel and use something with known syntax. -- wrobel