documentation and project organization (Was: Using LDAP with EAP-TLS)

[Gary Gatten]

If I knew more about it I would take my time to write some ... examples, use cases, case studies, whatever.  But, I can barely get by - each time I think I understand something it turns out I really don't.  I don't want to spread bad info so I say nothing - usually :)

IMHO a good starting point would be a single point of all "authorized" documentation: freeradius.org, Wiki, don't care - but it's frustrating when you find doc that seems legit that conflicts with other doc that also seems legit.  The single source of info then needs to have whatever is there vetted by those that actually KNOW whats what and kept current.

Unfortunately most people don't understand the details of PEAP, *CHAP, GTC, certs, etc. so they simply follow instructions verbatim.  If those instructions are "wrong", skip some steps, or even have basic typo's: it will lead to a lot of frustration not only to the novice user, but the smart people on here that constantly address the same "simple" issues.

I will step up to the plate and offer up a standard format for a "Recipe".  I will pick an "easy" deployment scenario - such as: "How do I configure FR to authenticate VTY access to my Cisco gear using AD on the backend, and users must be a member of GroupX"

I'm sure I will get some things wrong, but perhaps "we" can at least settle on a common template/format which will at least help moving forward.

-----Original Message-----
From: freeradius-users-bounces+ggatten=waddell.com at lists.freeradius.org [mailto:freeradius-users-bounces+ggatten=waddell.com at lists.freeradius.org] On Behalf Of John Dennis
Sent: Monday, May 16, 2011 1:52 PM
To: FreeRadius users mailing list
Subject: Re: documentation and project organization (Was: Using LDAP with EAP-TLS)

On 05/16/2011 02:20 PM, Arran Cudbard-Bell wrote:
> John,
>
> I believe Alan started a project to try and improve documentation in
> May last year. A few documents were converted RST format, but I don't
> think it was ever completed.
>
> I'm going to suggest the same thing I did back then. Add RST support
> to the Wiki, setup a well defined documentation structure (as in
> these are the subjects and example configurations that should be
> covered), and then roll page exports from the wiki into the
> documentation that 'ships' with FreeRADIUS.
>
> There's so much to document that it needs to be a collaborative
> effort.

Sounds like a fine plan to me. I do recall the documentation effort from 
last year. But the various promises of documentation seem to wither on 
the vine, the effort you cite is a perfect example. Maybe Alan's book is 
the answer, but that's been promised for a long time too. My basic take 
this is the classic developer's dilemma, developers want to write code, 
not documentation. When time allocation occurs the choice is to write 
code and defer the doc. But doc must get done, it needs an owner who is 
going to own the task and get it done.

FWIW, I constantly get complaints about the difficulty of using 
FreeRADIUS and the lack of usable documentation. Only last week this 
reached all the way to my manager who had to intervene and assert this 
is an upstream project issue and not something Red Hat can fix. Sorry, 
just being the messenger, just trying to ultimately help by saying there 
is a pain point and not sweep it under the rug.

-- 
John Dennis <jdennis at redhat.com>

Looking to carve out IT costs?
www.redhat.com/carveoutcosts/
-
List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html





<font size="1">
<div style='border:none;border-bottom:double windowtext 2.25pt;padding:0in 0in 1.0pt 0in'>
</div>
"This email is intended to be reviewed by only the intended recipient
 and may contain information that is privileged and/or confidential.
 If you are not the intended recipient, you are hereby notified that
 any review, use, dissemination, disclosure or copying of this email
 and its attachments, if any, is strictly prohibited.  If you have
 received this email in error, please immediately notify the sender by
 return email and delete this email from your system."
</font>