Web site docs are a suboptimal user-experience

[wcooley]

Having muddled my way through using Augeas with Puppet, I have been in a position to understand why many find it difficult to use. Personally, I think it's a great technology and would really like to see it grow and expand, over less disciplined and less formalized techniques of configuration file manipulation.

I regret that I cannot submit a pull request at this time, but I am hopeful that my attempt at articulating where I see trouble helps someone else. (Some of this I'm copying from a post I just made to the puppet-users list.) And anyway, I am reluctant to put much work into it without knowing that it would likely be accepted.

For one thing, there are at least 4 or 5 different "languages" involved, some of which are confusingly similar or bleed into each other:

1. Lens schema language
2. Path expressions
3. Tree structure & magic control files under "/augeas"
4. Tree manipulation and query commands which are similar but not wholly isomorphic:
   • "augtool" commands
   • Puppet parameters for Augeas type
   • Language bindings aka "public API": C, Ruby

I note that my list is similar to the main page, under the "Augeas is:" heading. But it really would be much quicker to grasp if these were delineated more clearly, possibly as subgroups under the "Documentation" link.

The lens schema language, which is the most difficult (and least generally applicable) has prominence under the "Documentation" link -- only the first 2 items, "Public API" and "Tree", are not about lens schema.

The C API is the only immediately-visible doc on the 4th item, which not the most user-friendly introduction.

The generated lens reference is a jumble of information that a regular user would need to know, like "What are the keys for the fields for this file type?" mixed with lens schema language.

The Puppet Augeas guide, which was migrated from Dominic's work in the deprecated Puppet wiki, is one of the best introductions; much of the content is not specific to Puppet and could easily be adapted to the general Augeas docs. The wiki docs under "Using Augeas" could also be more prominently visible as user documentation too.