On 28 Mar 2014, at 17:17, John Dennis <jdennis@redhat.com> 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"
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 behaviour 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.
I agree, there needs to be more documentation around fundamental concepts as opposed to specific scenarios. The behaviour of the server is actually really simple. Just an expanded version of http://wiki.freeradius.org/guide/Concepts with some diagrams would be nice. Arran Cudbard-Bell <a.cudbardb@freeradius.org> FreeRADIUS Development Team FD31 3077 42EC 7FCD 32FE 5EE2 56CF 27F9 30A8 CAA2