On Sep 1, 11:46 am, Douglas Garstang <doug.garst...@gmail.com> wrote: > For example, the very first sentence on the page starts with: > > "Learn how to distribute custom facts and types" > > How about a definition of what a custom fact and type are? Good > documentation generally doesn't assume that the reader knows all the > terminology being used without first defining or describing it in some > fashion.
You started off complaining about missing context, but that only holds up if you divorce the document from the overall documentation site. No, it is not a standalone document. Your point? Granted, if you hit that document without at least a general idea of Puppet's nature and structure then it wouldn't be much use to you. But in that case, briefly defining the terms wouldn't be much help: if you're not in altogether the wrong place then you need a much fuller introduction to the subject than is appropriate for such a narrowly scoped document. You are not (yet) among its target audience. But lo and behold! On that page there are links to Puppetlabs product overviews that introduce Puppet in broad terms, and at least four links to the top Puppet documentation, where can be found documents covering these terms and many others in considerable depth. The document in question is itself accessible from there, right next to the documents on writing the various types of plugins, and well below the Language Guide and resource and function references that provide the needed background. The context is all there, so I can only assume you are complaining about the general organization of the documentation site. I am confident that no one at Puppetlabs would claim it's perfect (nor do I), but "it doesn't work for me" is not a useful criticism. Do you have a question we can help you with? A suggestion for us to consider? Criticisms veiled as interrogatories need not apply. John -- You received this message because you are subscribed to the Google Groups "Puppet Users" group. To post to this group, send email to puppet-users@googlegroups.com. To unsubscribe from this group, send email to puppet-users+unsubscr...@googlegroups.com. For more options, visit this group at http://groups.google.com/group/puppet-users?hl=en.
