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:
- Make it as painless on me as possible;
- Be clear and articulate
- 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.
- Stay focused. Including a simple suggested change along with 2 feature requests is not helpful to me.
- 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.
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.