Why documentation is the way it is

[Lovaas,Steven]

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 at ColoState.edu
========================




-----Original Message-----
From: freeradius-users-bounces+steven.lovaas=colostate.edu at lists.freeradius.org [mailto:freeradius-users-bounces+steven.lovaas=colostate.edu at 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 at 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 at freeradius.org> FreeRADIUS Development Team

FD31 3077 42EC 7FCD 32FE 5EE2 56CF 27F9 30A8 CAA2