New CodeIgniter Documentation = Unicorn Party

Posted: 2011-10-06
Category: CodeIgniter

The CodeIgniter Community has been crying out for EllisLab and the development team to be more open and forward with information, developments, roadmaps, etc and EllisLab have taken this to heart. Yesterday they put up a "nightly build" of the new documentation which has been worked on in a GitHub branch for months and is not in develop and... the community said AAAAGGGGHHHHHHH! This post is an explanation of why the new documentation is amazing and most of the arguments against it are ridiculous.

In case anyone missed it, the announcement is here. Notice the words in the header "in Development". Instead of the old hand-crafted HTML documentation we now have documents written in LaTex (similar to Markdown or Textile) which is parsed using a Python system called Sphinx and can generate HTML or PDF documentation.

We need to install Python for docs?

NO! Python is the language used to build the documentation, and nobody is asking you to build the docs yourself. If you notice in the codebase the new latex files are stored in "user_guide_src/". What does this suggest? That they are the source files and not the final. We can run the build script when CodeIgniter is in a release branch, so that means when we prep v2.1.0 for final release we run a command, have the source and the build copy and everyone is happy.

But why Python? Why not a PHP system?

People should not be hung up on languages. The Ruby framework Ramaze uses Sphinx and they don't care, why should we? It's just a tool that does the job, and it happens to do the job better than any existing PHP systems.

Oh... ok well they don't look as good!

Remember that this is the initial push. The fact is that the documentation can now be styled without rewriting every single document manually. This means iterative improvements can be made until it looks amazing. You could even change the design if you wanted to go crazy, the fact is that the option is there.

Fine, but why is it still using Google Search?

Somebody complained that the new documentation was using Google for Search. The documentation has always used to use Google Search and currently it still does. Sphinx supports it's own built in search and that will get hooked up before things go live. Again, THIS IS AN EARLY PUSH.

But I was translating the user guide!

Well that is unfortunate, but what if we left it another month before releasing this plan? You'd have spent even MORE time working on it. The fact of the matter is that now the source files only contain text with basic Markdown-style markup you'll find translating it SO MUCH easier! The documentation can be built in the same way and there, you have awesome styled HTML and PDF documentation written in whatever language you like.

Anything else good about this?

As I've said, PDF export and search straight out of the box is bloody brilliant. We can theme the docs, we can now open them in our editor easily for reference, we have James Mathias working on the designs - and he can clearly design - and now we can build documentation quicker. A few times I've wanted to add a library but thought "Sure, but then I have to spend hours writing up all the bloody documentation". Now I can write that same documentation in minutes. Brilliant! The whole team feels the same and are glad to be able to write documentation quicker.

Summary

This is happening and it's a good thing. Every person making a complaint about a specific thing could just as easily say "I don't like X because of Y, can we make it work like Z?". Or, get involved. CodeIgniter is an open-source project after all. Send a pull request! This guy did.

Comments

Gravatar
Marco Monteiro

2011-10-06

Hey there Phil,
I think everyone will complain, but I still think the complaining is mostly about the new layout. I know this is still an early push but the fact is the layout will change in the future and I think almost all the peeps that use CI think the layout was awesome, heck many people like myself started using CI just because of the awesomeness of the user-guide.
About the rest, my first rants about it was just that, first rants. The post on Codeigniter news was not even out yet.
The rest of the features I think they're great, and yes I agree that for myself (since I'm translating the doc's to Portuguese) if this happened in a month would be a lot worst. I think it would be a better move if they did all those changes and added all the new features and kept the old layout. Believe me, most people wouldn't be complaining right now.
So, to all the features thumbs up. On layout, just stay with the old one. It was working fine, therefore don't need fixing.

Gravatar
Tárcio Zemel

2011-10-06

I really don't liked the new documentation, but I understood that this is only a "preliminary".

Well, if the "big dropdown" with sections and subsections of the documentation remains, it's fine...

Gravatar
David

2011-10-06

I think the big issue was adding it to the main repo instead of a branch or different repo with all of it imperfections and then putting out a statement saying better user guide was released and then going through once it was released and fixing all of the problems in such a public manor. It was just a big put off to people assuming now they need to learn Python and now they have to build their own docs. Now that the dust has settled, I think, for the most part, everyone is fine with the new docs. I can definitely see how new docs opens it up for a lot of cool stuff in the future.

Gravatar

2011-10-06

Hang on David, this is not in the main branch (which would be master), this is in "develop" which is where we work towards the next version and is not to be used as stable.

The statement was not saying "This is released" as you suggest, in fact it was titled "New User Guide in Development"! I don't think anyone could have been more clear about this. The article came after a quick "hey check this out" tweet confused everyone and was meant to stem the confusion, but only made it worse.

Nobody ever expected anyone to install Python, and why on earth would you need to learn to code Python even if you did? None of the team ever even considered the idea that people would jump to this crazy conclusion, so it was never mentioned.

The main problem here is that people didn't get it. People got confused, scared and angry because they didn't understand.

The point of the original tweeting was "Hey check out what we're working on" which is what people have wanted EllisLab to do for years. If people complain every time we give a quick update on development then we're back to years ago where everyone was left in the dark wondering what people were up to.

Now, as for feedback about the design, that should have been in the form of feedback instead of hundreds of tweets like "OMFG I'm going to puke" and "What is this shit, why did they even bother?".

Its rude, unhelpful and really, REALLY stupid.

Gravatar
Kcmerrill

2011-10-07

+1 for the markdown on steroids styled documentation. I'm digging it.

Gravatar
Vamsi

2011-10-08

CI documentation is the main reason why new comers find CI soo awesome , I hope that the chaged docs will also be newbie friendly ..

Gravatar

2011-10-08

Nobody would release a final product that is worse. The assumption that we would is almost an insult! :)

Gravatar
Jose Diaz-gonzalez

2011-10-09

Nice to see more communities pick up Sphinx - we're moving to it in Cake2.0. Are you thinking of using the Ajax search support? That's about the only thing that irks me, since a bad index download can potentially eff up your search results.

Gravatar

2011-10-10

The AJAX search will be implemented at some point I suspect. What are the circumstances where it is likely to screw up?

Gravatar
Mike Murko

2011-10-16

I really like where the documentation process is going!

One question: Will comments be integrated into this system? I saw a suggestion on Uservoice for doc comments and someone (can't remember who) said they were working on it. Is that being thrown out now?

One comment: From a relatively new CI user - I initially found the documentation to be slightly confusing because everything had to be accessed from an essentially hidden menu. It wasn't intuitive for me to find that "Table of Contents" each time to search for what I was looking for. Now that I know, I can find my way around well enough.

In the new docs ... I found it even harder! As far as I know the only way to access the menu is by clicking the "Table of Contents" link in the breadcrumb trail. I really think the sidebar with all the ToC should be visible on-screen all the time with content displayed on the right.

Again, I know it's an early build and the styling is up in the air, but I am pretty far from being a major contributor in this new documentation scheme so I hope that someone who is working on it can hear me out.

Gravatar
Phil Sturgeon

2011-10-16

Yep the ToC will be improved before it is released.

Nope, PHP comments will not be part of this documentation area, but potentially its own thing some other time. Guides are different to API documentation.

Gravatar
Mfawa Alfred Oneb

2011-10-19

I must say that accepting change is usually hard. I also complained about the change but like Phil has already said, confusion is the key contributor to most rants and ramblings about the new system. I believe the team will surely try their best to make it good and modernized.

Gravatar
Brett

2011-11-11

Hey Phil,

I find it hard to follow the develop around CodeIgniter. I see that they are expecting 2.1 to come out soon and 3.0 much after that. We're looking at extending CodeIgniter to use HMVC, but if HMVC is native in 2.1, we might wait. We're also considering Fuel or Kohana of course, but we rather not rewrite more legacy code than we need.

Is there any place where I can find information around CodeIgniter development in the future?

Gravatar
Phil Sturgeon

2011-11-13

Hey Brett,

Things may seem a little confusing at the moment. Basically we'd always planned on making a v2.1 and something I wanted to see in there was some basic HMVC. For various reason HMVC has slipped and will not be making it.

As for v3.0 that is going to be coming out much later. It is very common for software projects to work on creating multiple versions at a time. v2.1 will be a simple upgrade with small new features and a boat-load of new bug fixes so there is no worries updating, and v3.0 will be something a bit bigger that is more of a long-game plan.

v2.1 will not have the new documentation as it is taking too long to turn peoples feedback into reality, so we've let that slide to v3.0 meaning there is more time to make it awesome before it is released.

Gravatar
Khalil Tabbal

2011-12-28

Hi Phil,

Do you plan to use Sphinx Tool to generate PyroCMS documentation ?

If yes I would be really interested in translating the doc in French has i asked on twitter https://twitter.com/#!/rubatdub/status/150244165442224130

Gravatar
Reiny Júnior

2012-03-25

It takes a more flexible position by the community, sphinx maintaining the documentation update easier, it is commonly see software projects where the docs does not reflect well your code, justly because of the difficulty in update source docs.

It's very nice, agility the process with quality, it's always good =) !

Gravatar
Sunglasses

2012-04-28

<A href="http://www.oakleyoutlet-outlet.com//"> Cheap Oakley Sunglasses</A> <A href="http://www.oakleyoutlet-outlet.com//"> Oakley Sunglasses</A> <A href="http://www.oakleyoutlet-outlet.com//"> Oakley Sunglasses Outlet</A> <A href="http://www.oakleyoutlet-outlet.com//"> Cheap Oakley Frogskins</A> <A href="http://www.oakleyoutlet-outlet.com//"> Cheap Oakley Fast Jacket</A>

Posting comments after three months has been disabled.