Why documentation is the way it is

[Arran Cudbard-Bell]

On 28 Mar 2014, at 18:39, Arran Cudbard-Bell <a.cudbardb at freeradius.org> wrote:

> 
> 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.

Hmm, but people here are notoriously bad at taking things and running them
so in the interim I've compiled this comprehensive flow chart that should
cover pretty much every scenario.



Arran Cudbard-Bell <a.cudbardb at freeradius.org>
FreeRADIUS Development Team

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

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.freeradius.org/mailman/private/freeradius-users/attachments/20140328/6b8bba35/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: comprehensive_documentation.png
Type: image/png
Size: 57136 bytes
Desc: not available
URL: <http://lists.freeradius.org/mailman/private/freeradius-users/attachments/20140328/6b8bba35/attachment-0001.png>
-------------- 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/6b8bba35/attachment-0001.pgp>