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

[Alan DeKok]

John Dennis wrote:
> 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.

  Yup.

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

  Oh yes, lots.

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

  Yes, well... there isn't much to argue with there.

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

  Sure.  Except that 3.0 is pretty much ready now.

> I'll wager the time spent on this list answering questions will greatly
> diminish thus providing free time for feature enhancements and bug
> fixes.

  For me, time on the list is 30 seconds in between other work.  i.e.
"wait for compile: answer post".  It's really quite minimal, despite the
volume of messages I send.

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

  The level of frustration has diminished significantly with 2.0, and
again with 2.1.  The default configurations "just work", and the debug
messages have been improved to the point where mere mortals can
understand them.

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

  Look at github.  The only person other than me who's had meaningful
contributions in the last 2 years is Phil Mayers.  Many other "authors"
listed (e.g. Dante) are contractual obligations, implemented by me.

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

  There are a number of people who run multiple RADIUS servers (machines
&& products) for their living.  They're familiar with pretty much
everything.  We're all in their debt for answers, docs, bug reports, bug
fixes, etc.

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

  Project timeline: whenever

  What's upcoming: see doc/ChangeLog in git.

  release schedule: usually every 3-4 months

  organization / people / roles:
	code: Alan
	mgmt: Alan
	docs: Alan
	web site: Alan
	releases: Alan
	bug fixes: Alan
	Wiki: Peter Nixon

  Sense a theme?

  Alan DeKok.