Why documentation is the way it is

[John Dennis]

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"

Many of the thorny problems that trip up users are directly related to
their unique deployment requirements. One of the great things about
FreeRADIUS is it's enormous flexibility, but that's also it's liability
when it comes to documentation. There are often multiple ways to
accomplish the same thing and the final solution is often dictated by
constraints unique to the deployment or personal taste. Usually these
How-To's do not serve as a good generic guide.

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.

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.

-- 
John