The Puppet Labs Issue Tracker has Moved: https://tickets.puppetlabs.com

Feature #11402

Revise glossary and put it front & center in the docs

Added by Garrett Honeycutt almost 3 years ago. Updated over 2 years ago.

Status:ClosedStart date:12/14/2011
Priority:NormalDue date:
Assignee:-% Done:

0%

Category:-
Target version:-
Keywords: Affected URL:
Branch:

We've Moved!

Ticket tracking is now hosted in JIRA: https://tickets.puppetlabs.com

This issue is currently not available for export. If you are experiencing the issue described below, please file a new ticket in JIRA. Once a new ticket has been created, please add a link to it that points back to this Redmine ticket.


Description

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.


Related issues

Related to Puppet Documentation - Bug #6132: Use consistent naming Closed 02/03/2011

History

#1 Updated by Nick Fagerlund almost 3 years ago

Could you give a little more detail about what you’d like? Something like the core types cheat sheet, or something more like an online glossary?

#2 Updated by Robert Clark almost 3 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:

  • agent
  • node
  • catalog
  • manifest
  • module
  • template
  • resource
  • type
  • metaparameter
  • function
  • class
  • statement
  • parameter
  • expression
  • namevar
  • title
  • fact
  • etc.

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.)

#3 Updated by James Turnbull almost 3 years ago

There is a slightly out-of-date glossary here: http://projects.puppetlabs.com/projects/1/wiki/Glossary_Of_Terms

#4 Updated by Nick Fagerlund over 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.

#5 Updated by Nick Fagerlund over 2 years ago

  • Assignee set to Anonymous

#6 Updated by Anonymous over 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?

https://github.com/fredlf/puppet-docs/blob/fredlearn/source/references/glossary.markdown

#7 Updated by Nick Fagerlund over 2 years ago

  • Status changed from Accepted to Closed

Okay, that’s done! Iterating as needed. http://docs.puppetlabs.com/references/glossary.html

Also available in: Atom PDF