A few months ago a question in the very useful 'ask puppet' site attracted my attention. The authors of Beginning Puppet were asking for feedback about the desired content.
Since my answer has had some success, I'd like to report it here:
These are the things I would have liked to see as soon as I started experimenting with Puppet (in no specific order - this is mainly a brain dump):
What's a catalogue and how Puppet builds it
Recommended file structure for Puppet manifests
How to divide your infrastructure in environments
A clear indication that Puppet doesn't guarantee an "order of execution", and how to define dependencies between resources and classes (i.e. the "arrow" syntax to ensure that a class is always applied before/after another one).
Before ever writing a module, how to test it (and as a consequence, Continuous Integration for Puppet modules)
How to publish a module on github or puppetforge
A "build-up example" throughout the book. In other words, start building a module at the beginning, and keep adding elements as topics are discussed. For example, an apache module: start with making sure the apache package and its pre-requirements are installed, then add a file, then a template, then prepare the module for different environments, different OSs, etc.
Best practices for separating the module logic from the data, i.e. how to ensure that modules can be reused on different platforms/environments/OSs just with proper variable settings and without changes to the module logic.
Whether the hiera approach is recommended or not, and how to design a module with that in mind.
Best practices for dividing modules in classes
Variables scope, and best practices for variable names
Best practices for indentation, single/double quoting, module documentation
How to run Puppet in standalone/agent mode (so that the manifests can be verified easily locally)
Where Puppet looks for modules - how to install and use a 3rd party module
Common security problems
Load testing (e.g. with Gatling)
Continuous Integration (managing your modules with Jenkins or similar)