Why documentation is the way it is

[Arran Cudbard-Bell]

On 28 Mar 2014, at 15:59, <stefan.paetow at diamond.ac.uk> <stefan.paetow at diamond.ac.uk> wrote:

>>  Yes.  The Wiki exists for a purpose.  EDIT IT!  Why the heck are they
>> updating their pages, that no one else will ever be able to find?
> 
> As someone who has a set of instructions like this, it sometimes is an effort to:
> 
> a) document SOMETHING that works (or describes specific quirks for some local specifics)
> b) save others in the same organisation the effort of going through what they've gone though
> c) limit the audience to specific people
> 
> For c) one would expect to at least apply some set of permissions (i.e. visible only if logged into the Wiki), but not everyone is as particular about that as others are.
> 
> In my case specifically, because my work was EU-funded, I've had to have some sort of deliverable (and it had to be sharable with partners elsewhere), and since I had to start from a blank slate, it's easier to write things down. Not saying that EVERYONE must do that, but it's useful. :-)
> 
>>> 2) post after a long thread with 'I've now got it working' - but
>>> actually dont post any further details or feedback
> 
> Yes... although there's also the fear of "this is how I did it" and then getting flamed with "WTF did you do it that way??"

How you take that sort of response is obviously very personal, but i'd rather get feedback pointing to possible issues before they occur, instead of getting a call at 3am saying the RADIUS service has gone tits up.

> This may not be applicable to this list, but unfortunately, human nature tends to veer towards "If one mailing list is that way, then I'll treat most other lists with the same caution, JIC" (case in point, some recent threads that involved some stroppy comments).
> Now, as for editing the Wiki, you may wish to extend Omnigollum beyond just GitHub and OpenId (who uses OpenId?)

The person who requested we add it, and then complained bitterly that it was broken until they figured out it was a problem with their OpenID service.

> to make it easier to log in... not everyone has a Github or OpenId account (I didn't have either for quite a while).

Suggestions? It uses omniauth so it's absolutely trivial to add other auth methods supported by omniauth. Really, it's a one line config change per auth method. It even adds the little pretty auth icons to the selection page for you automatically.

We tried facebook and twitter, but it increased levels of spam and nastiness.

> That said though, the FR documentation is better than some other efforts I've had the misfor^H^H^H^H^H^Hpleasure to work with in the past ;-)

:)

-Arran

Arran Cudbard-Bell <a.cudbardb at freeradius.org>
FreeRADIUS Development Team

FD31 3077 42EC 7FCD 32FE 5EE2 56CF 27F9 30A8 CAA2

-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 881 bytes
Desc: Message signed with OpenPGP using GPGMail
URL: <http://lists.freeradius.org/mailman/private/freeradius-users/attachments/20140328/1ab0ccfb/attachment-0001.pgp>