My own thoughts, for what they're worth...
A "complete working examples" section would be invaluable. The most useful
part of the man pages for the command line & admin tools was the example
section... it ties everything together. Same for the examples in the admin
guide... a complete example to compliment the conceptual words is
priceless. Funny you mention it, but i was also disappointed in the N-Way
configuration example (17.4.3)... but because it was in the "new" config
file format, which i wasn't using.
Anyway, I understand you want readers to read thoroughly and try creating
their own configuration from scratch... but i've found it's rare that a
user will spend the time to "properly" understand something before they
actually try making it work. Rather, they try something, research/fix the
error, try again, research/fix, etc... whatever it takes to get it working
as quick as possible. In my experience, syntax diagrams and working
examples are the most important, time-saving (and sanity-saving) pieces of
documentation. Having working example configurations that are commented
thoroughly ("see section ____ for more info on configuration specifics for
this", "modify the following statements with your own specific values",
etc.) might be the best solution.
Thanks again for all your help
Show replies by thread