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

[John Center]

Hi John,

Just to chime in, I find all of the comments in radiusd.conf, etc. 
distracting & overwhelming.  I strip out the comments from the files I'm 
using - usually to find out how simple the configuration really is. 
When I'm missing something, I refer back to the original files & look up 
the relevant comment entry.  I would prefer all of the comments be 
assembled into straightforward documentation, using examples for the 
appropriate configuration sections.

My 2 cents, as we say...

	-John


On 05/16/2011 11:20 AM, John Dennis wrote:
> On 05/16/2011 10:13 AM, Alexandros Gougousoudis wrote:
>> Phil, I also understand a lot of things and I can read, but the
>> documentation of FR is not ideal. I've googled around, looked examples
>> and had more questions than before. Where are all these features
>> documented, like the "if then"-things in the conf, all the keywords like
>> "ok=return" and so on, what's the difference between Autz-Type and
>> Auth-Type? The only thing to get help is here on the list, on the net
>> you find a lot infos to FR 1.1 and 2 (one is deployinradius and one the
>> FR site) sites containing a little bit information, no much more than
>> the conf-files coming with the FR-archive. I'am not complaining, because
>> it's an open source project, but you should note that it's sometimes not
>> the lack of understanding than the lack of well documented features. And
>> if I can't find the infos I need in the docs, I start to try things out.
>
> +1
>
> I have to agree, the lack of comprehensive documentation, including an
> overview of concepts and the flow of operations is the greatest
> impediment to the success of FreeRADIUS as an open source project. The
> power and flexibility of FreeRADIUS is awesome, Alan and the other
> developers have done a wonderful job of providing the open source
> community with a fantastic piece of critical software. They have
> excelled at constant innovation and timely bug fixes. The response on
> the mailing is exceptional.
>
> But all these positive attributes are sometimes negated by the
> difficulty of understanding the system. Many justifiably feel
> configuring FreeRADIUS is a black art. It's often been pointed out that
> config files, doc directory and the wiki contains all you need to know.
> There is a modicum of truth in that. But the reality is it's very
> difficult to locate, extract, interpret and interpolate the missing
> pieces to form a functioning mental model in order to accomplish a
> specific deployment task.
>
> I've worked with FreeRADIUS for a while now and I'm still confounded
> things I don't know, incorrect expectations of behavior (e.g. != does
> not work for group testing). There are things which as far as I can tell
> are simply not documented. Just last week I had to help someone who was
> frustrated by the inability to add attributes to successfully proxied
> Auth-Accept's using a users file. By reading the source I found the
> postproxy_users_file config, as far as I could tell this is completely
> undocumented. When it comes to supporting users "Use the source Luke"
> isn't viable.
>
> I'd like to suggest the next most import task item for the team is not
> the 3.0 release, it's not any change to the code base. Rather the single
> most import task is producing comprehensive documentation collected in a
> single location augmented with cookbook examples of how to solve common
> deployment problems.
>
> I'll wager the time spent on this list answering questions will greatly
> diminish thus providing free time for feature enhancements and bug
> fixes. I'm also concerned at the obvious frustration expressed countless
> times on this list were folks have spent days, weeks, or in some cases
> months beating their heads against the wall in frustration. There will
> be a tipping point at some point in the future where that frustration
> will doom the project as it gets replaced by an alternative or forked.
> I've been in open source long enough to have seen this scenario play out
> multiple times.
>
> Just my 2 cents, worth what you paid for it :-) I'll now return you to
> your regular scheduled programming :-)
>
> And in case you missed it above, Alan and everyone else have done a
> wonderful job and provided a fantastic service to the community. All I'm
> suggesting here is the task priorities need to be tweaked a bit.
>
> P.S.:
>
> One thing which has been lacking in the project is public list of the
> project team. One might make the assumption Alan is the sole
> contributor, if so then that's truly amazing. But I'm going to guess
> others are involved. We would like to thank them as well and perhaps
> have some more insight into the project's organization. At best all I've
> been able to do in intuit based on reading this list and the dev list
> over an extended period that some list participants seem to have such an
> extensive knowledge it suggests to me they must be on the development
> team, either that or just like myself they've spent a lot of time
> reading the source code out of necessity. Questions like, what is the
> project's timeline, what is upcoming in new releases, what is the
> anticipated release schedule, how is the project organized, who are
> significant players and what are their roles are information unusually
> published by open source projects but have been missing (maybe just
> another example of missing documentation?).
>