RE: Looking for an editor for FreeRADIUS documentation
I would be willing to help as well-if its a collaboration. I can't code and this would be a way to give back. The money could be used someplace it's really needed. -----Original Message----- From: Ramm-Ericson, Johannes <Johannes.Ramm-Ericson@sonyericsson.com> Sent: Tuesday, May 18, 2010 3:14 AM To: 'freeradius-users@lists.freeradius.org' <freeradius-users@lists.freeradius.org> Subject: RE: Looking for an editor for FreeRADIUS documentation Hi, I'd definitely be willing to help out with this task. Particularly if it could be turned into a collaborative effort. Money is nice, however my primary motive would actually be to contribute to an outstanding piece of software that has been essential in my job. So, should I become involved in this effort you can happily use the money elsewhere. :) Best Regards, Johannes R-E -----Original Message----- Date: Tue, 18 May 2010 09:16:06 +0200 From: Alan DeKok <aland@deployingradius.com> Subject: Looking for an editor for FreeRADIUS documentation To: FreeRadius users mailing list <freeradius-users@lists.freeradius.org> Message-ID: <4BF23EB6.7080300@deployingradius.com> Content-Type: text/plain; charset=ISO-8859-1 In the interest of making the project better, we're looking for an editor for the documentation. The existing documentation is an "ad hoc" collection of files thrown together over a decade of effort, and written by many different people. We'd like to organize the documentation ("doc/" directory), and clean it up. We're looking for an editor with the following skills: [The entire original message is not included]
The problem with volunteer 're-factoring' work, is that although people mean well when they offer their assistance, it doesn't usually work out... They'll often spend a couple of weeks working on the task, get bored, figure they'll take a break and come back to it later, and it never gets completed. Offering financial renumeration means that the work is more likely to be completed, because there's a tangible pay off after it's finished. Sorry to by cynical, but that's my experience of things; and yes i've been on both sides. -Arran On May 18, 2010, at 5:35 AM, Jack Martin wrote:
I would be willing to help as well-if its a collaboration. I can't code and this would be a way to give back. The money could be used someplace it's really needed.
-----Original Message----- From: Ramm-Ericson, Johannes <Johannes.Ramm-Ericson@sonyericsson.com> Sent: Tuesday, May 18, 2010 3:14 AM To: 'freeradius-users@lists.freeradius.org' <freeradius-users@lists.freeradius.org> Subject: RE: Looking for an editor for FreeRADIUS documentation
Hi,
I'd definitely be willing to help out with this task. Particularly if it could be turned into a collaborative effort.
Money is nice, however my primary motive would actually be to contribute to an outstanding piece of software that has been essential in my job. So, should I become involved in this effort you can happily use the money elsewhere. :)
Best Regards, Johannes R-E
-----Original Message-----
Date: Tue, 18 May 2010 09:16:06 +0200 From: Alan DeKok <aland@deployingradius.com> Subject: Looking for an editor for FreeRADIUS documentation To: FreeRadius users mailing list <freeradius-users@lists.freeradius.org> Message-ID: <4BF23EB6.7080300@deployingradius.com> Content-Type: text/plain; charset=ISO-8859-1
In the interest of making the project better, we're looking for an editor for the documentation. The existing documentation is an "ad hoc" collection of files thrown together over a decade of effort, and written by many different people.
We'd like to organize the documentation ("doc/" directory), and clean it up. We're looking for an editor with the following skills:
[The entire original message is not included]
- List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Arran Cudbard-Bell wrote:
The problem with volunteer 're-factoring' work, is that although people mean well when they offer their assistance, it doesn't usually work out... They'll often spend a couple of weeks working on the task, get bored, figure they'll take a break and come back to it later, and it never gets completed.
I'd say the hard part is getting people to just write docs. It's not as sexy as programming, but it has arguably more *positive* impact on the end user. It looks like a good set of volunteers wanting to help. My suggestion is to convert the docs to "Restructured text": http://docutils.sourceforge.net/rst.html Quick reference: http://docutils.sourceforge.net/docs/user/rst/quickref.html Peter Nixon has converted a few documents over to RST: http://github.com/alandekok/freeradius-server/commits/master Look at the difference between the old && new versions. The new version is *automatically* marked up nicely on github! http://github.com/alandekok/freeradius-server/blob/master/doc/load-balance.r... This makes it *enormously* easier to read. Personally, I'd be happy if this effort results in the existing docs being converted to RST. It's easy to read as text, and looks good as HTML. Alan DeKok.
On Wed, May 19, 2010 at 3:12 AM, Alan DeKok <aland@deployingradius.com> wrote:
Personally, I'd be happy if this effort results in the existing docs being converted to RST. It's easy to read as text, and looks good as HTML.
The enthusiasm seems big enough. So how would this work? Get some people to submit an example doc that they've converted, and then you pick one which is best and assign the job? Or get people to convert some/all docs, and you decide which one contributes most? -- Fajar
Fajar A. Nugraha wrote:
The enthusiasm seems big enough. So how would this work?
http://freeradius.org/doc/community.html
Get some people to submit an example doc that they've converted, and then you pick one which is best and assign the job? Or get people to convert some/all docs, and you decide which one contributes most?
It's best to break the work down into simple steps. The above web page describes how we should work. If people have simple, clear goals, they don't need much coordination. They can do a set of small changes to one file, and push that back. This avoids overlap, and ensures that each change is easy to do. Someone with commit access can integrate the changes, where everyone else can pick them up. It takes a small bit of work to set up a git account on github. But after that, the extra steps required by git are pretty minimal. Alan DeKok.
On Wed, May 19, 2010 at 03:01:47PM +0200, Alan DeKok wrote:
Fajar A. Nugraha wrote:
The enthusiasm seems big enough. So how would this work?
It doesn't seem to be particularly enthusiastic any more. But that's what happens in the real world :) A non-trivial documentation format is a stringent documentation format. And also obviously humans suck :) In the meantime I've done some work fixing the Wiki. I invite everyone watching to have a look, it's now... no longer stuck in 2007. :) If you don't have an account or can't be bothered to edit, just shout here... -- 2. That which causes joy or happiness.
Josip Rodin wrote:
In the meantime I've done some work fixing the Wiki. I invite everyone watching to have a look, it's now... no longer stuck in 2007. :)
It looks quite a bit better, thanks. Alan DeKok.
participants (5)
-
Alan DeKok -
Arran Cudbard-Bell -
Fajar A. Nugraha -
Jack Martin -
Josip Rodin