Looking for an editor for FreeRADIUS documentation
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: - willing to do the work - can write reasonably clearly - basic knowledge of RADIUS The goal is to *organize* the documentation, not to write more. The existing documentation is basic, and could be improved through simple re-organization. No knowledge of "git" is required. Familiarity with "restructured text" would be good. We're looking to move the documentation to that format. If it matters, this is a *paid* position. We can't afford a lot, but we can afford to pay for work done. The rates will be negotiable based on quantity of work and results. Please send email to the list if you're interested. We can choose a candidate, and do the edits publicly, so people see visible progress. Alan DeKok.
Not meaning any disrespect to the "paid" offer, you could also reconsider to put up the current documentation in a "Wiki" style webpage, and from there everyone can work on the text that they think needs reworking. Regards HASSAN On Tue, May 18, 2010 at 13:16, Alan DeKok <aland@deployingradius.com> wrote:
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:
- willing to do the work - can write reasonably clearly - basic knowledge of RADIUS
The goal is to *organize* the documentation, not to write more. The existing documentation is basic, and could be improved through simple re-organization.
No knowledge of "git" is required. Familiarity with "restructured text" would be good. We're looking to move the documentation to that format.
If it matters, this is a *paid* position. We can't afford a lot, but we can afford to pay for work done. The rates will be negotiable based on quantity of work and results.
Please send email to the list if you're interested. We can choose a candidate, and do the edits publicly, so people see visible progress.
Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Nyamul Hassan wrote:
Not meaning any disrespect to the "paid" offer, you could also reconsider to put up the current documentation in a "Wiki" style webpage, and from there everyone can work on the text that they think needs reworking.
We already have a Wiki. Few people edit it. We already have a publicly available "doc" directory. Few people submit changes. Putting the existing docs into a Wiki won't magically make people submit changes. We're looking for an editor. All we want is someone who can organize and format the existing documentation. There is no need for "in depth" knowledge of RADIUS. There is no need for to write *new* documentation. That is work which is normally seen as "not fun". But it's needed. Therefore, the offer to pay for services rendered. Alan DeKok.
I would like to do this job, but my english is poor, so I can't do it :( 2010/5/18 Alan DeKok <aland@deployingradius.com>
Nyamul Hassan wrote:
Not meaning any disrespect to the "paid" offer, you could also reconsider to put up the current documentation in a "Wiki" style webpage, and from there everyone can work on the text that they think needs reworking.
We already have a Wiki. Few people edit it. We already have a publicly available "doc" directory. Few people submit changes.
Putting the existing docs into a Wiki won't magically make people submit changes.
We're looking for an editor. All we want is someone who can organize and format the existing documentation. There is no need for "in depth" knowledge of RADIUS. There is no need for to write *new* documentation.
That is work which is normally seen as "not fun". But it's needed. Therefore, the offer to pay for services rendered.
Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
-- ____________________ Ana Gallardo Gómez ____________________
I tried to "signup" to be able to edit the Wiki, but it seems that signup is disabled! Regards HASSAN On Tue, May 18, 2010 at 14:02, Ana Gallardo <ana.gallardo.77@gmail.com>wrote:
I would like to do this job, but my english is poor, so I can't do it :(
2010/5/18 Alan DeKok <aland@deployingradius.com>
Nyamul Hassan wrote:
Not meaning any disrespect to the "paid" offer, you could also reconsider to put up the current documentation in a "Wiki" style webpage, and from there everyone can work on the text that they think needs reworking.
We already have a Wiki. Few people edit it. We already have a publicly available "doc" directory. Few people submit changes.
Putting the existing docs into a Wiki won't magically make people submit changes.
We're looking for an editor. All we want is someone who can organize and format the existing documentation. There is no need for "in depth" knowledge of RADIUS. There is no need for to write *new* documentation.
That is work which is normally seen as "not fun". But it's needed. Therefore, the offer to pay for services rendered.
Alan DeKok.
- List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
-- ____________________
Ana Gallardo Gómez ____________________
- List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
On Tue 18 May 2010, Alan DeKok wrote:
Nyamul Hassan wrote:
Not meaning any disrespect to the "paid" offer, you could also reconsider to put up the current documentation in a "Wiki" style webpage, and from there everyone can work on the text that they think needs reworking.
We already have a Wiki. Few people edit it. We already have a publicly available "doc" directory. Few people submit changes.
Putting the existing docs into a Wiki won't magically make people submit changes.
We're looking for an editor. All we want is someone who can organize and format the existing documentation. There is no need for "in depth" knowledge of RADIUS. There is no need for to write *new* documentation.
That is work which is normally seen as "not fun". But it's needed. Therefore, the offer to pay for services rendered.
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. (Although there are a notable few people who have done some work at various times... You know who your are..Thanks.) 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 :-) -- Peter Nixon http://peternixon.net/
On Tue 18 May 2010, Alan DeKok wrote:
Nyamul Hassan wrote:
Not meaning any disrespect to the "paid" offer, you could also reconsider to put up the current documentation in a "Wiki" style webpage, and from there everyone can work on the text that they think needs reworking.
We already have a Wiki. Few people edit it. We already have a publicly available "doc" directory. Few people submit changes.
Putting the existing docs into a Wiki won't magically make people submit changes.
We're looking for an editor. All we want is someone who can organize and format the existing documentation. There is no need for "in depth" knowledge of RADIUS. There is no need for to write *new* documentation.
That is work which is normally seen as "not fun". But it's needed. Therefore, the offer to pay for services rendered.
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. (Although there are a notable few people who have done some work at various times... You know who your are..Thanks.)
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 :-)
What file format is the documentation in and roughly how big is it? I'm a technical writer and I'm interested.
bjlockie@lockie.ca wrote:
What file format is the documentation in and roughly how big is it?
Text. Not a lot, but organized fairly poorly.
I'm a technical writer and I'm interested.
Try: http://freeradius.org/doc/community.html Or, just convert the existing txt to rst, and send them as an attachment to the mailing list. Alan DeKok.
bjlockie@lockie.ca wrote:
What file format is the documentation in and roughly how big is it?
Text. Not a lot, but organized fairly poorly.
I'm a technical writer and I'm interested.
Try: http://freeradius.org/doc/community.html
Or, just convert the existing txt to rst, and send them as an attachment to the mailing list.
Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Ok, I'll look at it this weekend.
On 06/10/10 15:59, Alan DeKok wrote:
bjlockie@lockie.ca wrote:
What file format is the documentation in and roughly how big is it? Text. Not a lot, but organized fairly poorly.
I'm a technical writer and I'm interested. Try: http://freeradius.org/doc/community.html
Or, just convert the existing txt to rst, and send them as an attachment to the mailing list.
Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Is somebody already working on making .rst files because there are already some?
On 06/13/10 03:11, Alan DeKok wrote:
James wrote:
Is somebody already working on making .rst files because there are already some? Peter Nixon did a few in the "master" branch. I don't think any more changes have been made since then.
Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
I'll send you proxy.rst off list so there are no attachments on list.
On 06/13/10 03:11, Alan DeKok wrote:
James wrote:
Is somebody already working on making .rst files because there are already some? Peter Nixon did a few in the "master" branch. I don't think any more changes have been made since then.
Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
I did these: proxy.rst processing_users_file.rst cisco.rst variables.rst configurable_failover.rst There might be formatting errors but I think it is a good first pass.
James wrote:
I did these: proxy.rst processing_users_file.rst cisco.rst variables.rst configurable_failover.rst
There might be formatting errors but I think it is a good first pass.
OK. I double-checked them, and put them into the git v2.1.x branch. The suse/redhat/debian package scripts just install all of the files in the doc/ directory. So I think it's safe to fix the docs now. Alan DeKok.
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). -- 2. That which causes joy or happiness.
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
On Thu, Jun 10, 2010 at 11:59:57AM -0700, Arran Cudbard-Bell wrote:
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.
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.
But does that kind of a software actually exist?
- Still maintains blame information
Truth be told, mediawiki history isn't like git blame, but it's sufficiently close. Sorry for nitpicking :)
People are far more likely to contribute if the barrier to entry is low.
I'd perhaps rephrase that by saying that when people are unlikely to contribute, anything done to raise the barrier to entry has an amplified negative effect on the already low likelihood that a contribution will be actually made.
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.
Once again, that's exactly what Extension:ConfirmAccount tries to do. We don't need to reinvent anything, just get it installed and see if it works. -- 2. That which causes joy or happiness.
On Jun 10, 2010, at 12:11 PM, Josip Rodin wrote:
On Thu, Jun 10, 2010 at 11:59:57AM -0700, Arran Cudbard-Bell wrote:
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.
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.
But does that kind of a software actually exist?
Yes: http://www.mediawiki.org/wiki/Extension:RstToHtml ...
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.
Once again, that's exactly what Extension:ConfirmAccount tries to do. We don't need to reinvent anything, just get it installed and see if it works.
Well i'm up for a trial re-opening, but i'm not sure about Peter Nixon and Alan DeKok. -Arran
Arran Cudbard-Bell wrote:
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.
Ok. The RST format looks a lot easier than the Wiki format.
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?
Yes.
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.
We're also not in the business of account management. Someone like github.com is. If they had a Wiki that was RST *and* backed by git, it would be a clear winner. But people have been asking since 2008, and it's still not ready. Alan DeKok.
On Thu, Jun 10, 2010 at 10:44:27PM +0200, Alan DeKok wrote:
We're also not in the business of account management. Someone like github.com is. If they had a Wiki that was RST *and* backed by git, it would be a clear winner. But people have been asking since 2008, and it's still not ready.
OK, so to clarify, if we installed Extension:ConfirmAccount on the FR Wiki, we would not reenter the annoying account management business, nor jeopardize any live content; but we would lower the bar of entry for more people to contribute. Coupled with Extension:RstToHtml, that could become a decent origin for the not-so-volatile copy in freeradius-server git. The process of copying wouldn't be trivial (probably?), but for a hired editor it wouldn't be much of a problem either. -- 2. That which causes joy or happiness.
On Jun 10, 2010, at 2:48 PM, Josip Rodin wrote:
On Thu, Jun 10, 2010 at 10:44:27PM +0200, Alan DeKok wrote:
We're also not in the business of account management. Someone like github.com is. If they had a Wiki that was RST *and* backed by git, it would be a clear winner. But people have been asking since 2008, and it's still not ready.
OK, so to clarify, if we installed Extension:ConfirmAccount on the FR Wiki, we would not reenter the annoying account management business, nor jeopardize any live content; but we would lower the bar of entry for more people to contribute. Coupled with Extension:RstToHtml, that could become a decent origin for the not-so-volatile copy in freeradius-server git. The process of copying wouldn't be trivial (probably?), but for a hired editor it wouldn't be much of a problem either.
If media wiki is anything like pmwiki, the source files are very easy to parse (just flat files with some metadata in the header). -Arran
On 06/10/10 16:44, Alan DeKok wrote:
Arran Cudbard-Bell wrote:
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. Ok. The RST format looks a lot easier than the Wiki format. I'm trying to get this installed: http://catherinedevlin.blogspot.com/2009/08/enthoughts-restructuredtext-edit... 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? Yes.
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. We're also not in the business of account management. Someone like github.com is. If they had a Wiki that was RST *and* backed by git, it would be a clear winner. But people have been asking since 2008, and it's still not ready.
Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Am Dienstag, 18. Mai 2010 09:16:06 schrieb Alan DeKok:
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:
- willing to do the work - can write reasonably clearly - basic knowledge of RADIUS
The goal is to *organize* the documentation, not to write more. The existing documentation is basic, and could be improved through simple re-organization.
No knowledge of "git" is required. Familiarity with "restructured text" would be good. We're looking to move the documentation to that format.
If it matters, this is a *paid* position. We can't afford a lot, but we can afford to pay for work done. The rates will be negotiable based on quantity of work and results.
Please send email to the list if you're interested. We can choose a candidate, and do the edits publicly, so people see visible progress.
Alan DeKok.
Hi, I'd like to contribute. I can write some chapters. Since I am no native English speaker I'd need a lector to check my writing. And I have some experience in artice and book writing. Perhaps with the help of all the volunteers we can finish the book. You define the structure and people contribute text. Greetings, -- Dr. Michael Schwartzkopff MultiNET Services GmbH Addresse: Bretonischer Ring 7; 85630 Grasbrunn; Germany Tel: +49 - 89 - 45 69 11 0 Fax: +49 - 89 - 45 69 11 21 mob: +49 - 174 - 343 28 75 mail: misch@multinet.de web: www.multinet.de Sitz der Gesellschaft: 85630 Grasbrunn Registergericht: Amtsgericht München HRB 114375 Geschäftsführer: Günter Jurgeneit, Hubert Martens --- PGP Fingerprint: F919 3919 FF12 ED5A 2801 DEA6 AA77 57A4 EDD8 979B Skype: misch42
I can both write chapters, and also edit the work of other contributors who are not too well versed in English. I would still request Alan to reconsider the wiki approach. Perhaps, you can dictate the structure of the wiki, and we can all contribute to fill up the contents. But, whatever the way you choose, we all would like to help out the best we can. Like Jack said above, I too am not a C / C++ developer, and think this would be a good way to give back. Regards HASSAN On Tue, May 18, 2010 at 19:18, Michael Schwartzkopff <misch@multinet.de>wrote:
Am Dienstag, 18. Mai 2010 09:16:06 schrieb Alan DeKok:
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:
- willing to do the work - can write reasonably clearly - basic knowledge of RADIUS
The goal is to *organize* the documentation, not to write more. The existing documentation is basic, and could be improved through simple re-organization.
No knowledge of "git" is required. Familiarity with "restructured text" would be good. We're looking to move the documentation to that format.
If it matters, this is a *paid* position. We can't afford a lot, but we can afford to pay for work done. The rates will be negotiable based on quantity of work and results.
Please send email to the list if you're interested. We can choose a candidate, and do the edits publicly, so people see visible progress.
Alan DeKok.
Hi,
I'd like to contribute. I can write some chapters. Since I am no native English speaker I'd need a lector to check my writing.
And I have some experience in artice and book writing.
Perhaps with the help of all the volunteers we can finish the book. You define the structure and people contribute text.
Greetings,
-- Dr. Michael Schwartzkopff MultiNET Services GmbH Addresse: Bretonischer Ring 7; 85630 Grasbrunn; Germany Tel: +49 - 89 - 45 69 11 0 Fax: +49 - 89 - 45 69 11 21 mob: +49 - 174 - 343 28 75
mail: misch@multinet.de web: www.multinet.de
Sitz der Gesellschaft: 85630 Grasbrunn Registergericht: Amtsgericht München HRB 114375 Geschäftsführer: Günter Jurgeneit, Hubert Martens
---
PGP Fingerprint: F919 3919 FF12 ED5A 2801 DEA6 AA77 57A4 EDD8 979B Skype: misch42
- List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
Need to give something back to the Open Source community. So I'd very happy to contribute with this project. I have some experience contributing to standard bodies such as WBA which I'm the Cochair of R&D and authored some of the stage 2 documents in the WiMAX Forum (GRWG) currently in RiLTE (GSMA) and previously in CDG "Packet group". Strong development background and FreeRadius' user. Ramon Castillo $HOME = GMT + 1 ----- Original Message ---- From: Alan DeKok <aland@deployingradius.com> To: FreeRadius users mailing list <freeradius-users@lists.freeradius.org> Sent: Tue, May 18, 2010 9:16:06 AM Subject: Looking for an editor for FreeRADIUS documentation 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: - willing to do the work - can write reasonably clearly - basic knowledge of RADIUS The goal is to *organize* the documentation, not to write more. The existing documentation is basic, and could be improved through simple re-organization. No knowledge of "git" is required. Familiarity with "restructured text" would be good. We're looking to move the documentation to that format. If it matters, this is a *paid* position. We can't afford a lot, but we can afford to pay for work done. The rates will be negotiable based on quantity of work and results. Please send email to the list if you're interested. We can choose a candidate, and do the edits publicly, so people see visible progress. Alan DeKok. - List info/subscribe/unsubscribe? See http://www.freeradius.org/list/users.html
participants (10)
-
Alan DeKok -
Ana Gallardo -
Arran Cudbard-Bell -
bjlockie＠lockie.ca -
James
-
Josip Rodin -
Michael Schwartzkopff -
Nyamul Hassan -
Peter Nixon -
Ramon J. Castillo