[eluser]jdfwarrior[/eluser]
Well this issue with this is, even Derek still has to get things approved too. He can't just change stuff to whatever he wants. Which is why we're talking about us just submitting changes, letting Derek run a diff on the files we submit, and letting him pass that along for approval.
Would eliminate a lot of the grunt work for Derek and give him time to focus on other things, and would allow the community to contribute their efforts toward the betterment of codeigniter as well.
[eluser]Colin Williams[/eluser]
Yeah, there's that balance that is always taken with CI because it is "owned" by a software company. I think appointing one community member that they can trust like an employee is just a better bridge to the community, even if it still isn't 100% open-source-like. Baby steps..
But overall I like that EllisLab has a firm grip on the framework. Pure open source often lacks the sort of polish CI has.
[eluser]Derek Allard[/eluser]
Oh boy. See... this is why I didn't want to wade here to begin with - we start with a few trivial guide fixes from Jedd and now I'm at 2 pages of forum and probably 10 hours work from jdfwarrior  In seriousness, of the 5 things you suggested, only half are quick and/or painless for me, the others would involve hours and hours of painstaking work. As I said earlier, I'm every bit as busy as all of you, and I dare so moreso then most. I don't mind implementing fast things that add clarity; but wholesale rewrites are beyond what I can offer right now.
Also, just wanted to touch on a few other things in this thread for completeness. Yes I absolutely can make any changes I want, every employee has that privilege. That we go to each other when there are large changes on the table is a sign of respect, not hierarchy.
We implemented user submitted comments in the EE documentation, and I'll investigate it for the CI docs.
SVN commit privs are unlikely at this stage. Sorry.
I like the idea of a community liaison. Is this something you're volunteering for Colin, or just suggesting?
[eluser]Colin Williams[/eluser]
Actually, Derek, I once drafted an email about this very topic, volunteering to be a community liaison for improving the user guide, with your email in the TO: field. Ultimately, I deleted the draft because I knew--as much as I wanted to help and as much as I saw the need for such help--I knew I didn't exactly have the time needed to fulfill that promise.
So, at this point, it's a suggestion, shrouded with a personal desire to volunteer for it, suppressed by the reality of 60-hour work weeks.
I'm actually toying with the idea of starting a separate user guide, distributed under my own control. That way, I've not made unfulfillable promises to EllisLab, but I'd have the freedom to take the user guide in any direction I'd want. In fact, the ideas have been raging since I read through this topic today At the time, I'm more comfortable with this option. And of course, anything produced on my end would be offered as contribution to EllisLab.
[eluser]jdfwarrior[/eluser]
A separate community maintained user guide would be a cool idea as well but without some kind of perm link on the site somewhere, most would never know or find out about it. Highly doubt EL is gonna go for linking to a completely separate user guide of ours.
Derek, I realize it was a list that required big change and require much work, which is why I stopped where I did. My apologies the idea of a community liason isn't bad. Derek also, in mention of the amount of time required to fulfill this task.. Jedd and I are both volunteering to do whatever we can. We told tell the rest of your guys we did the work for you it'll be our secret, shhh! Haha
[eluser]jedd[/eluser]
For want of somewhere else to discuss this stuff ...
The load->model() function - described in the general [url="http://ellislab.com/codeigniter/user-guide/general/models.html#loading"]Models[/url] page, and then in the [url="http://ellislab.com/codeigniter/user-guide/libraries/loader.html"]Loader Class[/url] page.
The two definitions conflict - or at least, the Loader Class fails to mention the third parameter that can be used to pass a configuration array for database access, or just a boolean to force database access. The Models page only mentions this parameter in a different section, after Loading A Model.
A style guide would make contributions easier. I like the [ optional_param ] approach that most texts use, but this isn't in play anywhere in the guide, so I don't imagine it's hugely popular in The Labs. The subsequent section in the Load page - for load->database - reads thus:
$this->load->database('options', true/false)
I can't work out how you'd want to represent [ true/false/$array ] - which is what the third parameter to load->model() actually is.
Derek - if an alternative user guide was set up for a collaborative effort, refined somewhat, mostly consistency updates and the like - would that be seen as a hostile act / politely ignored / entertained being merged back into the official guide at some point?
Colin, jdfwarrior - would you guys entertain a collaborative approach anyway, or would you want to run your own private repository?
[eluser]Colin Williams[/eluser]
I don't see any concerns for merging the efforts at some point, and certainly no concern for hostility. EllisLab would be free to use whatever they wanted from the collaborative guide as they see fit.
jedd, I imagine the effort would be maintained by a choice group of developers. It wouldn't be a free-for-all wiki. However, I see each topic page as having a discussion area where users can suggest additions, modifications, etc.
[eluser]jdfwarrior[/eluser]
[quote author="Colin Williams" date="1255398644"]I don't see any concerns for merging the efforts at some point, and certainly no concern for hostility. EllisLab would be free to use whatever they wanted from the collaborative guide as they see fit.
jedd, I imagine the effort would be maintained by a choice group of developers. It wouldn't be a free-for-all wiki. However, I see each topic page as having a discussion area where users can suggest additions, modifications, etc.[/quote]
I seconds this idea, where there would be a selected group of people who could modify whats there. I don't think it should be wide open for anyone to change, that would only lead to problems. The comments section could be moderated to allow users to suggest updates and such to the guide.
And yes I would be willing to help. You guys just let me know where we wanna start to get it all rolling
[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).
[eluser]Colin Williams[/eluser]
Here's my thought on the process. Three tracks that largely overlap.
I. Design
A. Develop a new IA for the User Guide. Yes, we all know and love the current design, but it doesn't fully account for: Extended examples, function references, source view, discussions, etc. We don't need to start from scratch, just grow.
B. Create a visual design implementing the IA.
C. Develop templates/front-end code.
II. Content
A. Port existing user guide to the new IA.
B. Ongoing content creating by moderators + community.
III. Development
A. Use a CMS to implement IA, design and content.
Quote:Writing and maintaining a hybrid restricted-access-wiki-with-moderated-comments-addenda would be a non-trivial task.
I can think of a few CMSs that provide this out-of-the-box.
|
