Revise glossary and put it front & center in the docs
|Assignee:||Fred Lifton||% Done:|
We need a cheat sheet for those who do not live and breath Puppet to understand the vocabulary. This will further empower them to search and speak in a meaningful way.
#2 Updated by Robert Clark almost 2 years ago
We were discussing the benefits of having a glossary, so that it’d be possible to have intelligent conversations about Puppet without munging terms, especially when those terms are overloaded (within puppet or possibly between Puppet and other programming languages). The goal is to make it easy to describe various puppet-related things unambiguously and have a quick-reference dictionary. And, arguably, to also ensure consistency in the Puppet docs — I think we still found “recipe” mentioned in there somewhere as a synonym for manifest or code.
As an example, what is the proper word to use to describe all of the puppet code that exists in your source repo that is then bundled into a catalog and delivered to an agent running on a node? “Manifests”, probably, but that is potentially ambiguous when specifically referring to the “manifests” vs. “modules” directories (and the manifests directory within a particular module). This particular distinction gives us an approved way to refer to the collection of our puppet “code” (not to be confused with the actual source code for the puppet product itself, since “code” can also be overloaded) as opposed to our puppet configs (which I’d take to be the .conf files for puppet itself, and not system configs managed by puppet, since “configs” can also be overloaded).
A possible starter list of terms to define and include in such a glossary:
Currently, the only way to properly pick up all of this vocabulary (or to check one’s interpretation of a definition), is to thoroughly read or search all of the docs; a glossary/dictionary for quick word look-ups would certainly help expedite things.
(edit: to clarify, these definitions should be dictionary-style on one page, using short definitions, possibly hyperlinked to the sections of the full docs that describe format and usage of said term in great detail, but obviously not trying to redefine the syntax and usage of those terms being defined. I think that’s why we called it a cheat sheet — it’s a one-stop shop for quick info on the vocabulary in order to be better equipped to find the right full document to go read for more information.)
#4 Updated by Nick Fagerlund almost 2 years ago
- Subject changed from vocabulary cheat sheet is needed to Revise glossary and put it front & center in the docs
- Status changed from Unreviewed to Accepted
Yeah, that glossary will be a good starting point. Robert, thanks for the detailed response/request.
#6 Updated by Fred Lifton almost 2 years ago
Here is my first take on revising the glossary. I have not made an effort to edit the definitions (much), I’m more looking for feedback on the list of terms. Anything obvious I’ve missed? Anything on the list that ought not be?
#7 Updated by Nick Fagerlund over 1 year ago
- Status changed from Accepted to Closed
Okay, that’s done! Iterating as needed. http://docs.puppetlabs.com/references/glossary.html