Arran, I think you're onto a very important point... especially for those of us who benefit from the visual in our learning habits. I personally benefited a lot by drawing out the basics of RADIUS in general and the FreeRADIUS server in particular, so that I could communicate with our network team and get our old servers updated to support the roll-out of eduroam on our campus. Your suggestion of some expansion and graphic help for the overall layout resonates with me... mental models, concept maps, and all that. A picture can help cement the basic landscape, and make more advanced conversations easier to sustain. I'm in a busy mode and it will take me a while (no promises before summer?), but I'll commit to putting this kind of thing together. Steve ======================== Steven Lovaas IT Security Manager Colorado State University Steven.Lovaas@ColoState.edu ======================== -----Original Message----- From: freeradius-users-bounces+steven.lovaas=colostate.edu@lists.freeradius.org [mailto:freeradius-users-bounces+steven.lovaas=colostate.edu@lists.freeradius.org] On Behalf Of Arran Cudbard-Bell Sent: Friday, March 28, 2014 12:39 PM To: FreeRadius users mailing list Subject: Re: Why documentation is the way it is 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