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

[John Dennis]

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/