Why documentation is the way it is

[Alan DeKok]

John Dennis wrote:
> I think one of the problems with user contributed doc is it ends up being:
> 
> "A How-To of how to solve my unique problem exactly the way I did"

  Very true.

> Many of the thorny problems that trip up users are directly related to
> their unique deployment requirements.

  Yes.  TBH, the configuration is documented well enough to show people
how to put the pieces together.  Heck, after 15 years and 1000's of
configuration items... *I* read the documentation to see how it works.
I can't be bothered to remember each individual configuration option.

> To my mind the fundamental documentation problem is not the lack of
> specific documentation detailing the details, there is plenty of that.
> What's missing is an overarching explanation of how all the pieces fit
> together and/or can be assembled. My general observation is many users
> have problems because they do not understand how the server works in
> broad terms and how that behavior can be adjusted to meet certain
> deployment requirements.

  Well... we've tried to document that in the doc/ directory, the Wiki,
and the comments in radiusd.conf, and sites-enabled/default.  It's not
perfect, but it's correct.

  The various books I've seen are lacking, TBH.

> Until folks have a working mental model of what's going on any
> documentation about pulling a specific lever or turning a certain knob
> isn't going to help them because they don't understand the "why" behind
> the recommendation.

  Hence my continual "unhelpful" replies of "What PROBLEM are you trying
to solve?  Don't ask how to configure X, describe the PROBLEM".  And the
complaints from a subset of users who don't understand that I can't help
them until they answer my questions.

  Alan DeKok.