Why documentation is the way it is

[Arran Cudbard-Bell]

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

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 881 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: <http://lists.freeradius.org/mailman/private/freeradius-users/attachments/20140328/000bb2b6/attachment-0001.pgp>