The documentation project's conventions, best practices, and general habits.
Occasionally, like with 2.6, a major version changes the terminology or the names of various tools and services. After one of these changes, all documentation not addressing backwards compatibility should use the new names and terminology exclusively.
Eventually, we may need a more prominent "decoder" document; in the meantime, the Tools reference will do.
The docs project favors (but never favours) American spellings.
Systems running puppet master should be usually called "puppet master servers," "puppet master nodes," or "puppet masters." Systems running puppet agent should usually be called "agent nodes." In general we should avoid using "server" and "client" alone to describe these roles, because agent nodes (clients) are almost always servers themselves.
- Node: Any computer; all other info must be gleaned from context. When using this term, you shouldn't expect that it necessarily means agent node.
- System: Synonym for node.
- Agent or agent node: a computer running puppet agent on a regular basis.
- Server: Cannot be assumed to mean puppet master server, since most systems
running Puppet are servers in some capacity. If you mean puppet master
server, say so, or just call it the puppet master. By contrast, the
serversetting in puppet.conf's[agent]block has sufficient context that it's obviously referring to the puppet master. - Host: Since we have a "host" resource type, the term "host" should not be used to refer to a computer.
Here's how to style the word "puppet," depending on how it's being used:
- When referring to the entire suite/solution, Puppet is a normal proper noun.
- When referring to an executable tool by name (e.g. "puppet agent"), it is
downcased; the principle here is that when an utterance is both a proper name
and part of an executable statement, we should treat it more like code than like
a name.
- However, tool names obey sentence case (e.g. "Puppet doc is your new friend.") and title case.
- When the name of a tool is used as an adjectival noun or is referring to a piece of hardware by synecdoche (e.g. "your puppet master server" or "your puppet master" or "managing ten puppet agents"), follow rule 2.
- When the name of a tool is functioning as a complete shell command, style
it as code (e.g. "...and then run
puppet agent"). Code spans in Markdown are `delimited by backticks`. If you are instructing the reader to run the tool but have not provided a complete command (e.g. "...after the task completes, run puppet agent again with the same command line flags."), follow rule 2. - Puppet Dashboard is always treated as a normal proper noun in both expanded and shortened ("Dashboard") forms. This is because Dashboard never gets executed by a user at the command line, and thus is only a product name and not an executable statement.
The basic rationale to use when capitalizing words is: is this a proper noun? This turns out to be a squirrely question, but the judgement we went with during the PE2 launch and have felt pretty okay about since is that PRODUCTS are proper nouns, but FEATURES are not. That is, "live management" wouldn't be capitalized, and neither would "faces" -- they aren't independent products. In fact, we don't even capitalize the console.
This was one of those tricky calls that we might revisit at some point, but for the time being, I (NF) feel pretty good about erring on the side of not looking like a bad fantasy novel.
Surround placeholder text with either curly braces or angle brackets, depending
on the context. When possible, try to word placeholder text such that the reader
won't try to enter it verbatim. e.g.:
"Puppet file server URIs are formatted as
puppet://{server hostname (optional)}/{mount point}/{remainder of path}."
If you're quoting a shell command inline, context should keep it from being confusing. If quoting a group of commands and responses as a code block, prefix the commands with $ or #. For clarity, you can choose to prefix shorter responses with >, but longer responses are usually visually distinctive enough to be obvious.
Per feedback from Product (Nigel), the docs (especially those dealing with PE)
should generally prefix example commands that need superuser privileges with
sudo, rather than explaining the privileges needed (too much) or expecting
readers to pick up on the distinction between $ and # (not enough).
Use standard verbs to describe the things that can be done to Puppet constructs:
You define a class or resource type when you write its implementation. For
defined resource types, this is done with the define keyword; for classes,
it's done with class some::class { ... }. You could consider the definition of
native resource types to happen in their Ruby type/provider code.
To declare a resource or class is to create an instance of the thing that
was previously defined. That is, you define a type, but you declare a resource.
Declaring classes is done with the class { "some::class": attribute => value,}
syntax or with the include statement.
Resource (and parameterized class) declarations consist of a type, a title, and
a series of attribute => value pairs.
When defining a resource type or a parameterized class, you specify a list of
parameters it accepts (e.g.
define gitrepo($giturl, $path = $title, $branches = [master]) { ... }).
Thus, parameters are relevant to the implementation, and attributes are relevant to the interface.
Documents meant to help troubleshoot problems should follow these principles:
- Be action-oriented
- If users can pick and choose from a number of options, use bulleted lists. If users should do EVERY step in a series, use numbered lists. The latter should be more common.
- Steps should be accompanied by actual copy-and-pasteable commands that test whatever the step asks you to check.
Documents in this repo are in Markdown format with several extensions.
- Each file should begin with YAML frontmatter, per Jekyll's requirements. See any file for an example.
- The Markdown processor we use (Kramdown) supports the definition list and table markup extensions from PHP Markdown Extra. The docs use these in various places.
- We also use several Jekyll-specific Liquid tags. If we ever switch backends,
the behavior of these will have to be re-implemented. The tags we're using
include:
- {% include %} --- Insert
a snippet from the
_includesdirectory. If you're including into body text, the snippet can contain Markdown and what-have-you, but if you're including directly into a template, it must be mostly normal HTML (although it can contain more Liquid tags). - {% highlight %}... some code ...{% endhighlight %} --- This
uses the
pygmentizecommand to color up code examples. Seepygmentize -L lexersto see a list of what's allowed. Note that this automatically puts everything within into a<pre><code>block, so indenting it is superfluous, but as long as the language is something like ruby where indentation is non-semantic, indenting reduntantly can make your text editor's Markdown highlighting behave better, especially if the example is full of underscores or something. To highlight Puppet code, use {% highlight ruby %}. There's a Puppet lexer available, but it doesn't ship with pygments by default, and much of our puppet code actually blows it up, so we should turn it on in a dev branch at some point and submit bug requests. https://github.com/rodjek/puppet-pygments-lexer/ - {% capture %} ... {% endcapture %} --- Capture some text so you can render it elsewhere in the page with {{ }}.
- {% iflink "Link text", "/link/destination.html" %} --- Custom to our
site. Renders a normal link, unless it would point to the current page, in
which case it renders
<span class="currentpage">Link text</span>. {% render_nav %}--- If the YAML frontmatter specifies a filename in its "nav" key, this tag renders that file, which it will find in the_includesdirectory. Otherwise it renders the default nav snippet from_config.yml. This should really only be called from templates.
- {% include %} --- Insert
a snippet from the
There is also at least one case where we abuse Markdown:
-
Asides in an article should be styled as Markdown blockquotes. We should properly be using
elements, but:- It's really convenient to make a Markdown blockquote.
- We don't use blockquotes for actual QUOTES anywhere in the docs, which effectively makes it an abandoned element.
- The Markdown spec, such as it is, says processors should ignore any further Markdown formatting inside an explicit HTML block element (like ), so using the proper tag would entail spewing raw HTML around our documents. This can be turned off in some processors, but we would prefer to not rely that heavily on implementation details, plus turning it on might wreck something else.
This is the current most-canonical list of the words we have for parts of the console UI, as of January 12, 2012's meeting w/ Randall.
the bar at the very top is the MAIN NAVIGATION or PRIMARY NAVIGATION.
Clicking on an element in the main navigation takes you to a SECTION of the console. This word is vague and unconcrete because the divisions between the sections are vague and unconcrete.
The sidebar is the SIDEBAR. It contains:
- the NODE STATE SUMMARY
Clicking a state takes you to the NODE LIST (changed node list, failed node list, etc.).
- the GROUP SUMMARY
Clicking a group takes you to that group's PAGE.
- the CLASS SUMMARY
Clicking a class takes you to that class's PAGE.
From the nodes section, or any other list of nodes, you can get to a node's PAGE. Likewise for any class, group, or report; each individual object has its own PAGE.
A report page contains TABS that show different parts of the report.
The landing page of the reports section is the REPORTS LIST. You can refer to the inventory search section as a section, a page, or just the inventory search. Likewise the file search.
The live management SECTION contains three TABS, and a FILTERABLE NODE LIST (or just NODE LIST) in the SIDEBAR. the manage resources tab contains a RESOURCE TYPE NAVIGATION for switching between RESOURCE TYPE PAGES. Resource type pages contain a LIST OF RESOURCES, any of which can be clicked to reach the RESOURCE DETAIL PAGE. (These can be referred to by type: "package detail page.") the advanced tasks tab contains a TASK NAVIGATION for switching between TASK PAGES.