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 <[email protected]>
Looking to carve out IT costs?
www.redhat.com/carveoutcosts/
-
List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
