CI User Guide question

[eluser]jedd[/eluser]
Okay. I see two disparate things that need to be done. The first is a major overhaul of the manual - tidying up the inconsistencies that we know about, formalising the prototype/definitions for functions, providing a more consistent layout for code and output examples. But (probably) not making huge structural changes to it. In other words, it would still look and feel like the user manual we know and love.

The second is a far more nebulous beast - I gather we seem to agree that something like the moderated php.net documentation repository, where each function (or in our case, probably, helpers and libraries) have an attached forum/wiki component, clearly delineated from the official documentation at the top of the page, for contributed code partials, gotchas, alternatives, neat tricks and so on.

For the first activity, I reckon a dump of the extant svn user_manual directory into github (say) with the few of us having commit access into it, and we just beaver away at it, arguing between ourselves when and where necessary (though I suspect the handful of people passionate enough to push contributions are likely to agree more often than not). The good thing with this is it means anyone else can grab a copy really easily, and more importantly it makes it really easy for EL to pull the changes back into their user_manual if they want to. I've no idea on git->svn capabilities, though I gather they're less adept than svn->git - but I see this as a minor issue. Apart from anything else I reckon svn would simply be too limited for such a collaboration, and pointless given we're not going to have EL svn access in any case. (And yes, I'm a github fanboi.)

For the second activity, I can't see how this could be done on any site other than this one (nor could it run on multiple sites, for obvious reasons). I see such a system as a fairly major under-taking, and one that EL is unlikely to look at doing any time soon. I conclude this in part from the state of the wiki - both in the quality of the contributions in there being unlikely to make EL think user contributions are going to be of a usefully high standard, but equally the quality of the wiki software per se indicates that it's not very high on EL's list of priorities. Writing and maintaining a hybrid restricted-access-wiki-with-moderated-comments-addenda would be a non-trivial task. This obviously presents somewhat of an impasse, and one that I don't see being resolved any time soon.

Happily I think the first activity can commence right now, with current tools, at low cost, easy buy in, good results, yada yada. That it may assist, circuitously, in the realisation of the second activity is a bonus (but not one that I'm hugely optimistic about).