CI User Guide question

[eluser]jdfwarrior[/eluser]
This is really aimed more at the admins and such but I was just wondering if you guys had ever considered making the user guide to be somewhat like a wiki. Just seems like it would be nice to have someone other than you guys, because I know you stay busy with other things, to make minor updates or changes to the user guide as needed.

For instance, I made mention a while back of something that I thought needed to be corrected in the Loader Class documentation. It still hasn't been changed.

Example:
The Loader Class documentation on the View method is shown as (the heading)
$this->load->view('file_name', $data, true/false)

It shows the class, the method, and all possible parameters available to that method in the heading so that you can quickly see it. The next method down however, the model method, is shown as: $this->load->model('Model_name'); The documentation does go on to mention later that there is an option second parameter to set the name used to access the method, but for consistency, that optional parameter should be included in the heading as well. If a small group of users or something could be appointed to make updates and such to the user guide, then things like this could be updated quickly and easily, without having to bother you guys with such small, insignificant things.

There are also some things that need to be updated in the Cart Class documentation..
the format_number function isn't referenced, and in the sample code, there is a product_options function used that I believe should just be 'options' and not 'product_options'

Just a thought..

[eluser]jedd[/eluser]
This would have to be my biggest problem with the guide, too - the lack of consistency between pages. I find it's much easier to read a function definition that includes all the parameters, than having to scan through the next few paragraphs of text to glean the number, and nature, of the parameters.

I speculate - and this is based purely on having worked in similar sized organisations in the past - that the guide was developed by several authors, and they each have their own preferred format. Two things result as a consequence - different formats, and no likelihood of one format being chosen across the board (until one of the stakeholders leaves the company).


I really like the way PHP.net have the man page for each function, and beneath that an area of user-contributed notes. It's heavily moderated (read: effort required) but the payback is just huge, I reckon, for the 'average user'.

I'd be against turning the user guide into a wiki -- have you ever looked through the CI wiki?! -- unless you could really nail down who had access to it. And even then you'd have the same types of arguments between people with different ideas. The only difference there is that the EL guys have to then manage the little bitty feelings of all those people that don't work in their office as well.

FWIW I just posted, to Derek, a couple of changes to the manual - a fairly painless affair for all concerned I gather. It'd be much nicer if the user guide was separated out and run as a git-managed project, though. Hmm, was about to put a smiley on there, then realised that this approach might work better - a distributed wiki, if you will, with veto at the primary repository, and a low, but non-zero cost of entry for would-be contributors (which effectively keeps the kind of people who think defacing wikis is cool out of the way).

[eluser]jdfwarrior[/eluser]
I guess wiki was a bad way to put it, I wouldn't want anyone to have access to it, because some times there are users that are just insistent that something is wrong in the guide and it's not. A controller list of user's in the community would be nice though.

My big thing is, CI's documentation is excellent. It's one of the main things that drew me to CI and I know that holds true for many others as well. Obviously functionality and performance and everything that the developers handle is top priority, because if it's not a good product.. even if it has stellar docs, it still sucks. CI is awesome, and has really good documentation, but there are a few areas it could be tweaked to make it more consistent and a little more informative in my opinion.

A distributed wiki would be cool as well, good thought.

[eluser]BrianDHall[/eluser]
I would just like the addition of PHP.net style declaration of parameters and return values for any function mentioned in the manual. Like in it's own call-out block, even if redundant with the rest of the text of the manual it would be a nice and quick, easy reference.

[eluser]jdfwarrior[/eluser]
I've been going through the User Guide a lot the last few days making a textmate bundle, and I swear, the further I go, the more and more errors and just randomly ambiguous stuff that I find... *sigh*

[eluser]Derek Allard[/eluser]
http://derekallard.com/blog/post/getting...er-manual/

You guys inspired me

[eluser]jdfwarrior[/eluser]
[quote author="Derek Allard" date="1253229246"]http://derekallard.com/blog/post/getting...er-manual/

You guys inspired me [/quote]
Hope you didn't take my comments as bitchy or rude, it really wasn't the intention if that's how they came across. As mentioned in my previous posts, I've noticed several things lately that I'll try to shoot you a few emails on and see what you think about getting them updated/corrected.

Once again, my apologies if it seemed rude.

[eluser]Derek Allard[/eluser]
Didn't seem rude at all, I'm grateful to see people who care enough about it to mention it (thanks). Yes, by all means feel free to email me.

[eluser]jdfwarrior[/eluser]
Derek: If you didn't hate me before, you will when you get this list

[eluser]Derek Allard[/eluser]
Just make things easy on me. If you give me a list that will take 10 hours to implement, then none of it will get implemented - I assure you I'm just as busy as you are