DerekAllard.com

Getting changes made to the CodeIgniter manual

CodeIgniter User Guide

The CodeIgniter manual is almost universally praised by the community*. I’m proud to say that we work very hard on our documentation at EllisLab - in fact as a coder, I’m forced to write the docs for anything I add or change. This means that they are pretty up to date, and reasonably complete.  Could things be better? Of course! There’s always room to improve anything, and our docs are no exception.

What I’d like to focus on here is how to go about improving the docs, and one approach to giving your suggestion the best possible chance of getting included.

The first thing to understand about our docs is that currently they are not editable by the community. This means all doc changes need to go through a staff member. There are advantages and drawbacks to this, but for now that is the way it works. This means that you’ll need to contact me, or another staff member with your suggestions.  Someties changes come in that are simple, and straightforward (thanks Jedd) and easy to implement; but often that isn’t the case.  Allow me to indulge for a moment if you would :)

If you want your changes made, a few of the best things to do are:

  1. Make it as painless on me as possible;
  2. Be clear and articulate
  3. SAVE ME TIME! If you have an alternative suggestion, then type it out with html so that I can copy and paste it. Spellcheck it (for the love of god please spellcheck it), and finally tell me exactly where in the docs you are referring to. Vague “you spelled function wrong” references make me dig and cost me time.
  4. Stay focused. Including a simple suggested change along with 2 feature requests is not helpful to me.
  5. Be polite. Note: asking if I “even bothered reading my own docs” is not polite.

An example of a good suggestion

Hey Derek, there’s a missing parameter on $some_function on $some_page ($exact_url). I think $new_parameter needs to be listed after $existing_parameter like this [example followed].

So that person has (a) given me an exact page and place on the page (no looking needed); (b) provided SHORT, clear guidance; (c) not given me a 4 page dissertation on the philosophy of manual writing; (d) not clouded the email by also making 2 feature requests and attaching their version of a helper that they “know is better”. Brilliant! I’m likely to read that over and drop it in on a coffee break.

Allow me to share with you some of the “help” I often read (both in email and on forum):

There is a missing link in your guide.

Um… where?

The example you give for the mail class isn’t clear.

Which example, and why isn’t it clear?

You need to rewrite the explanation of how encryption works.

Why? How? Which explanation, all of them?

And my personal favourite:

Derrickk I really love Code Ignite but I also used Rails once and it did this thing differently and frankly its much better but I understand why you didn’t do it that way because its much harder and you probably don’t have time to do it that way and oh yeah have you noticed by the way how long I can make a sentence without using any punctuation? Anyways as I was saying the guide is really good and is one of the main reasons my friend told me to try code ignite and I think its good but could be much better if onely you switched the doctype of every page to be HTML 3.2

Notice of course that they spelled my name and “Code Ignite” wrong.

I say all this by way of encouraging enhancements. We want to hear your suggestions, and the easier they are for us to implement, the better it’ll be for everyone.

If you think you have something worthwhile to add, or a change that would add clarity or utility to the docs, then please feel free to contact me with your suggestions. I’m always happy to hear from a fellow Igniter!

* Many experienced developers find them too simplistic, and would prefer the technical style of PHP.net. I don’t disagree at all, that is an excellent format, but our docs are deliberately aimed to be less formal, and more “tutorial” in nature. That’s not to say one is better then the other, only that it has worked well for us.

This entry was made on and filed into CodeIgniter.

Comments

Ian G. Clifton wrote on

What about simple typo fixes?  A couple of times I have created “Trivial” bugs in the bug tracker (e.g., http://codeigniter.com/bug_tracker/bug/7516/), but I’m not sure if that’s the best way to report them.

Derek wrote on

Yup, the bug tracker is absolutely perfect for those types of things Ian (thanks!)

Jamie Rumbelow wrote on

It might be interesting to see how helpful an in-depth technical API Documentation resource could be with in-line commenting. I love the CI docs, but I also love PHP.net’s excellent documentation too.

Is there any plans/space for something like this? Another benefit to this is that we could dumb down the town of the standard documentation to be more like one big mofo tutorial.

Nirmal wrote on

Maintaining the user guide as tutorial is good but php.net’s documentation is far better, IMO the best. The whole community can contribute lot to the documentation with example codes than you/your team. You can the depth of the documentation on php.net. I think it will be better if you take some steps to remove that “business minded” bad brand people put on your name. CI is the best framework I used so far and I like it. I would really like to see it stand out as the best in every field.

jeremy wrote on

I propose that you create a doc_change_request function in a new helper!

Then, folks can simply execute the function to make the request.

doc_change_request($function, $page_url, $description, $kudos);

nice and simple, eh?

Emil wrote on

What kind of software is used to work with the CI docs? Self developed or a modified wiki of some kind? There should be an easy way to document code… and I haven’t found one yet (besides inline)

Derek wrote on

Thanks guys, great comments!

@jamie: There is absolutely room for that style of docs, and I agree that it is excellent. At this point it would be a considerable effort to go back and doc everything that way, but would probably be worthwhile (you volunteering :))

@Nirmal: We allow user comments on the ExpressionEngine docs, and I’m looking into a similar system for the CodeIgniter docs. It would be helpful I agree, but still requires massive effort on our part to keep spam and/or no value comments out of there. I assume you’ve seen the many examples of popular (often open source) projects that allow this, whose documentation is almost worthless now because of spammers.

@Emil: They are just standalone HTML files under source control. This allows us to have anyone edit them, and fosters distribution as part of the CodeIgniter download.

Sam IT wrote on

Return values could be helpful to understand what a function would return without reading through CI’s code and/or var_dump it (which could be different, depending on the input).

As mentioned, user comments could be helpful too. I don’t think that user guide that is distribute with CI should have those, it is HTML after all but on CI’s website, it could be helpful.

Keep it up!
Sam

Trae Regan wrote on

Greetings Derek, I posted a thread in the forum at one point: http://codeigniter.com/forums/viewthread/125535/

Bretticus wrote on

Thanks Derek and EllisLab for sharing this framework with the whole wide world. Whenever I “look under the hood” to extend the functionality somewhat, I’m always impressed by little innovations here and there. No wonder the performance is so good! CI has changed the way I code websites (for the better.)

The documentation is great. If people will actually read it, they will find it’s pretty much all there. Unfortunately some developers can not leverage the knowledge because they do not understand programming principles. There are plenty of websites to learn programming or PHP. I don’t feel that CI docs needs to be anything more than a manual for the framework. It really is excellent.

I do think the comments idea is not a bad idea. Perhaps comments could be hidden by default (like the menu.) As for spam, I am astounded by how well http://akismet.com/ works for my Wordpress blog.

Thanks again.
Brett

Ed Finkler wrote on

I think I mentioned this before, but I’ll bring it up again:

I really think the CI docs should be built in something *other* than HTML. The reason being that, as HTML (and partly because of the structure of the HTML) it lacks a hierarchical structure, and it’s problematic to convert the docs into other formats.

I’ve often considered, for example, packaging the CI docs into a desktop and/or mobile apps with full text search features. The structure of the documentation as it is makes this a lot more challenging than it could be.

In order to make the docs more accessible to multiple formats, I’d propose using a simple text-based source format like AsciiDoc. This can be converted into various formats, and the build processes can be pretty easily scripted.

As for content, the one thing I think is *really* lacking from the docs is return info on functions and methods. This is critical info that really should be in there.

All that said, you guys have done a great job. The docs for CI are one of the reasons I continue to recommend it as a good framework choice.

Bruce Alderson wrote on

One thing that has frustrated my teams and I about the CI docs: the examples are trivialities (often not functional).  While the general sense of a concept is visible in the examples, the nuances are not.  Just a minor nit though.

grk wrote on

I recently got into development with CI (after trying out almost every PHP web framework there is) and although I’ve _really_ enjoyed it so far I found the manual also a little bit too brief on some subjects - and yes, I am talking about the framework only, not on “how to do PHP”.

However, my main problem up to now has been the lack of return values in the manual.

Since CI also gives you much freedom on how to organize your code I’d say that a “list of coding recommendations” would be helpful. I have seen CI tutorials (listed in the wiki) where database inserts were placed in the controller.

grk wrote on

Correction: I just noticed that there is a section in the manual covering style guidelines, however, as far as I can see there is no recommendation for code placement.

Johan wrote on

As far as for the style of the documentation I think I like the look-and-feel of the CI doc’s more than any other docs. It’s clear, has good visual separation between sections and so on.

What I really miss is the API section. The return values, method parameters including _optional_ parameters and so on.

For what the procedure of posting improvements to the docs I don’t like comment systems. It’s unstructured and the examples posted, even to do good, get outdated when the codebase changes.

No, make it for the people who see improvements really easy to post a bug report. E.g. a link beside each section to post a bugreport (like editing in mediawiki, but then to post reports).

Bruce Alderson wrote on

For what it’s worth, user contributions for code examples and clarifications would be swell for the CI docs.  I would be happy to write or add to examples based on questions I’ve seen asked, and would follow any style guidelines presented (as would many users).  It becomes a problem of moderation and review, but that may be less effort than writing them in the first place.

Just a thought.

David Dotson wrote on

Uh, something I was looking for in the documentation, and I couldn’t find, but then realized that what I was looking for didn’t exist (so the docs complete). Anyway, the problem I ran into is that you can use an array to establish a GROUP BY in Active Record, but you can’t do the same thing in an ORDER BY clause. Not a big deal, but thought it’d be nice if they were consistent:
This works:
$this->db->group_by(array(‘goonie_name’,‘goonie_age’));
This won’t:
$this->db->sort_by(array(‘goonie_name’,‘goonie_age’));

David Dotson wrote on

Well, back on topic to the documentation, the only thing I’d like to see updated are the video docs. They are a little behind, and some of the basic functions have changed since then I think.

Teejay wrote on

I can’t say I am not happy that there’s an update. The CI Manual still rocks better than most documentations.

Albert Freeman wrote on

Your documentation is absolutely brilliant. Don’t change a thing. When I talk to people about CodeIgniter, the clear, reader-friendly, complete documentation is one of the points I emphasize.

Steve Heinsch wrote on

An idea for you Derek that might help make this less painless for you :)  What if every page (maybe even for each function in the manual) have a link where you can report suggestions/corrections. Something with javascript so you click the link and a little textarea pops up where a person can add their issue.  Then you would have direct reference to the function in question (or page).

Some additions I think would be very beneficial.
1) Allow user comments ala php.net
2) Brief changelog ala php.net.  Like this function changed from CI 1.7.x.  Method added in CI 1.7.x blah blah.  It would make it a lot easier for working on CI sites which might not be the current version without having to go dig up the manual for that specific version.

William Hickocks wrote on

Contact with clients or potential users is a good thing to do. I’m pleased seeing that a creator is open for discussion about his product and is not just thinking about how to show people that he is great and other are not :) The cooperation is best way of improving things. Keep up the good work!