Looking for an editor for FreeRADIUS documentation

[Arran Cudbard-Bell]

On Jun 10, 2010, at 11:38 AM, Josip Rodin wrote:

> On Thu, Jun 10, 2010 at 09:07:32PM +0300, Peter Nixon wrote:
>>>  We already have a Wiki.  Few people edit it.  We already have a
>>> publicly available "doc" directory.  Few people submit changes.
>> 
>> Yes. I'll second Alan on this. It was my idea to setup the wiki, and I
>> spent a LOT of time on it for a year or so, but have unfortunately not
>> seen as much input from the community as we will have liked.
>> 
>> If there is only going to be a small group of people editing the docs, git
>> and RST work much better than a wiki, and save maintaing both mediawiki
>> and an SQL server :-)
> 
> IMHO you saw little input because you had a wiki that was rendered
> practically dead for three years. There was nothing there even just to
> tell newbies that there *is* a procedure to get an account, let alone
> anything that would actually entice them to edit.
> 
> Similarly, keeping docs in another, even less trivially accessible format,
> will not alleviate this problem - it stands to reason that it can only
> make it worse. Paying people to overcome that problem could make things even.
> 
> Yet, it will be that much harder to get an account and submit changes
> because it will require a little bit more toolset learning for users and
> a little bit more interaction from the admins.
> 
> That's why I mentioned that ConfirmAccount mediawiki extension - it will
> reduce the amount of bother for the admins, while still allowing the users
> to use minimal necessary skills to do their edits.
> 
> Obviously I have nothing against people also working on documentation in
> git, whether paid or not - the rule in documentation is that duplication
> is not something frowned upon by default (unlike with software).

My idea was to install an extension to the wiki that allowed rendering of RST. The documentation would be kept up to date on the wiki, and at official release time those pages would be pulled in from the wiki and bundled with the rest of FreeRADIUS.

Advantaged are:
- Easy to edit
- No learning curve for GIT
- Still maintains blame information
- Instant feedback with the preview function when testing out syntax
- One source for all documentation
- Documentation available without downloading package or src bundle.

People are far more likely to contribute if the barrier to entry is low. The reason for the wikis zombie like status is, as other people have stated that there is no official procedure to request an account, and no automated account creation. I remember the issues with spam, so auto account creation is out. Maybe have a a registration mailing list where people can pick requests off and create the accounts manually?

The barrier to get an account has to be sufficiently high that spammers won't go through the hassle and sufficiently low that people will still contribute.

-Arran