served by the Type Reference and Function Reference documents,
and found the Language Tutorial to be a handy introduction.
If I were to ask for more, it would be a Language Reference,
and a comprehensive index, because I find search tools
generally lacking.
On Mon, Aug 27, 2007 at 10:24:04AM -0500, Luke Kanies
wrote:> If there were unit tests for documentation sufficiency, I''d feel
> pretty differently about it, but there aren''t. I''ve
often written
> documentation that I thought was sufficient only to have it either
> entirely ignored, for who-knows-why, or castigated as being entirely
> unrelated to what people want.
As someone who compulsively writes documenation, I know exactly what
you mean. It seems that no one appreciates the effort invested.
But when I look at things from my perspective, I find it so much
more rewarding working with software that is well documented, and
so I try to emulate that. OpenBSD is an excellent example of how
thorough documentation can really help.
As for it not being what people want, it might be because different
people want different things. I want reference documents, and only
grudgingly use tutorials, while there are others who swear by tutorials
and shun reference documents.
If our project decides to use Puppet long term (we are evaluating it
still), then I may have some time to commit to the documentation. In
the mean time, I wouldn''t presume to tell you what to do, only what
I as one potential user, consider valuable.
Alex
