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.