[Date Prev][Date Next] [Chronological] [Thread] [Top]

Re: Incorrect snippet in delta-syncrepl example in admin guide?

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