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

[Alan DeKok]

Arran Cudbard-Bell wrote:
> 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 received a number of patches from one person, a few from another one
or two, and nothing else.

  I've been saying for ~10 years that this is a community effort.  I'd
*like* additional documentation, but I don't get paid to write it.  I
get paid to write code.

  The community has spoken: documentation isn't important enough.

  I'd like to change that, but I'm busy.

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

  My $0.02 is that we should use github.  They now support git-backed
Wikis, which use "markdown".  It's close enough, and has a lot of benefits.

  But it requires converting the existing Wiki pages.  I'm not inclined
to do it, as I have too many other things to do.

> There's so much to document that it needs to be a collaborative effort.

  It's not hard.  Read the comments in the config files, and write a
document summarizing them.  Add one or two simple examples.

  Alan DeKok.