Thread

I like this thread. I read a whole bunch of negative reviews based on a early version of some awesome work that isn’t final. Wow where do some of you guys get the energy to type up some of that rubbish that you put on here. I mean none of you had any input on the original docs design, so why now that EllisLab decide to get input from users there is so much negativity, it’s not even constructive criticism.

This reminds me of something a friend told me. “A guy goes on a air plane and while in flight, the air hostess announced that there is now free wifi available on the flight, around 10 mins later the wifi goes down and the guy starts to complain. The air hostess said to him a few minutes you didn’t even knew wifi existed on this flight and now you know and its now down you complain.”

People remember that EllisLab is not obligated in any way, shape or form to share the direction they are taking on the docs with you or even ask you for input. Go make money off the thing already and stop complaining about what the docs look like.

Here are some questions for you negative folks.
Is the docs still readable?
Is it as clear as the previous docs?

Keep up the good work EllisLab team and all the Reactor Folks.

I just checked out the new user guide and really don’t understand all the fuss about it. To me, it still looks very clean, easy to read and well formed. And if all this can be done in a much easier and more efficient way, that’s awesome!!

Being both a designer and developer I can understand that some people are disappointed by the design of the new user guide. But I really don’t think it’s such a huge difference and that the new user guide looks much better than a lot of other documentations out there.

The only thing I don’t like is the light blue background on tables and code snippets. But hey, that’s just a personal thing and I’ll get used to it…

Keep it up and thanks for making that change happen that will save lots of work on updates in the future and in the end - will keep CI going!

Here’s my five pennorth:

1. The original docs were not comprehensive.

2. I prefer the PHP Manual style of declaring description, parameters, results and especially the examples.

3. I like the new MVC(?) approach of separating the content from the style.

4. I miss the bold red.

5. Question: How to eliminate the infuriating time taken to display the TOC.

Keep up the good work.

The docs needs a complete redesign IMO (from what the new one is at the moment), because the current docs are really wonderful and easy to read.

I took a look at the new build.  Fantastic job guys!  The new TOC alone makes it much easier to use.  Parameters, Returns, etc… very nice also.

STYLE: I do like the more refined “smooth” looks of the new user guide, although I do also dislike the blue top bar and would like to remind you that high contrasts are essential for such a type of doc.

TOC: When I first met the drop down TOC of the actual CI I felt like “WOW this is how user doc should be”! So clearly the side sliding TOC with the multiple step navigation is less than optimal compared to what you have now.

Docs: The actual content structuring of the old and new docs are still not optimally-arranged yet (have a look at MSDN or doxygen). The descriptions themselves are also not exhaustive enough in many cases. They usually lack a simple (real world) example and examples of some special cases (which is always a pain to research).

Doc-Tool: But I totally agree, that if you really coded the doc in pure HTML before (WHY??) then using Sphinx must seem like a jump into Warp-Age for you. And it really doesn’t matter if Sphinx needs Python or not, since Python is so easy to install and use especially on Windows.

To throw a few pennies on the pile, here is what I think:

1. I love - I mean absolutely LOVE - the existing docs.  It was, in fact, the deciding factor on why I selected CI as a development platform, the documentation was vastly superior to all other choices for MVC framework. I’ve recommended CI on as many projects as I could citing the comprehensive and complete documentation as a major plus.  I’ve re-written my Dreamweaver Extension site with Code Igniter because I love it (because it does rock as a framework) and understand it so well (because of the docs).  Serious major props to the developer of the documentation for CI.  You rule!

2. My book mark page for CI is http://ellislab.com/codeigniter/user-guide/toc.html
This allows me to find all of the main level items quickly as I don’t always remember what category an item is under.  I am concerned I won’t have a comparable page to be my starting point.  I click on TOC and I get the slide out without details as to where everything is. So my first suggestion is to provide a page, like the existing TOC which has all of the relevant classes listed under their sections.  This would allow the documentation to be as flexible and easy to navigate as it is now.  If that means the slide section covers the whole page - or - you make a separate page (preferred), that is OK. (call it extended TOC)

3. I do love the list of methods at the top of the page in the new docs, while I knew the method was there on a page, I had to scroll to find it. This is easier.  It would be nice if these were displayed across the page and not just in a list down the page (so more can be seen at once, like on the database active record list)

4. The fluff comment - the style is unattractive, again, the existing documentation is a beautiful work of art, with CSS, you can probably make the new docs match the style of the existing docs, tweaking it as needed.  While it is somewhat fluff, the new design/layout/colors do make the documentation less usable as it isn’t designed as well as the existing and - yes, we’re largely coders and all, but I prefer well designed documentation because it makes Code Ingiter easier to use and - when I recommend CI - it is better for management/owners to look at and see a well designed documentation section.

I do understand the need to make the documentation more maintainable for EL, in doing so, I do hope that the stellar work on the existing documentation for style and all will be the model that the new docs will aspire to mimic as closely as possible.  To do less will make Code Igniter less attractive to new developers (who don’t know where anything is at) and less of a selling point for my clients.

Thanks for “listening”

The pulldown menu might be “outdated” to some, but it is a very efficient use of screen real estate when compared to the current model being proposed.  You can see everything at one glance and not have to scroll all around trying to find what you are looking for.  Would be nice if subtopics would appear when clicking on a topic without a page reload and having to reclick on the ToC to pick a subtopic.

Still famously good docs, no matter how crappy they look. Other frameworks wish they had such docs.

The breadcrumb system makes no sense. The breadcrumbs imply a trail of how you got to where you are, or at least a hierarchical organization of the path to the page you are viewing. I would assume that clicking on the links in the breadcrumbs would load up the requested page. Clicking on “Home” takes you to the documentation home page, etc. However, for some reason clicking “Table of Contents” opens up an unexpected sidebar with an unusable table of contents. The behavior is contrary to the behavior of every other link in the breadcrumbs, and simply doesn’t make sense.

Once the table of contents is open, you can’t even expand/collapse the sections to find the section you want. You have to click the top level section, then from that page reopen the “Table of Contents” sidebar, then click into the sub section.

The current design of the user guide an inferior replacement to the old one. I am glad it is easier to maintain, but it is a step backwards for usability.

I would also include some “return to top” links in some of the larger sections. Or make “Page Contents” a fixed sidebar. In fact, make the header fixed and improve the functionality of the “table of contents” widget and you would have a user guide that is even easier to use than the old one.

The color is a problem. Especially source code is difficult to see.

How could you?!

I loved Codeigniter because of the clean,structured and easy to read documentation.
To give you an example :

- Clicks needed to open overview in old version: 1 - new version : not available
- Clicks needed to find what you need in old version : 2 ( 1 site load ) - new version 4
- It took me some time to guess where to go for the contents list

And I want fire to be red, I want my code to be ignited and burn, not to melt like ice.

Definately voting +1 for bringing back the top slide-down TOC from the “old” docs. We got used to it and it lets us navigating to the pages (overview of the most important classes/helpers/pages) we look very quickly.
Have no problems with the content pages itself.

Or to quote the 2 points from Pascal’s post:

• I used to be able to scan all of the available helpers and libraries with one click, which was particularly useful when I didn’t remember where a function lived.

• In the same vein, I need to click more to get to a library/helper reference.

Insert Expletive here “F3$%%@&^” the docs, fix the long list of bugs first. Enough said… well maybe not, documentation though important only really matters when the core system is “almost” bug free. I can read all the docs in the world but if a bug exists, clear and concise documentation won’t magically solve it. Noobs like me of course always need the basic docs but in most cases Google is your friend.

I’m with everybody else here, please bring back the old style.

The current documentation is fine, I’m able to search for what I wanted and read and be gone.

The new system just doesn’t make sense, there’s no “sub-topic” drop down. At least with the current docs, I can see all the libraries, with the new docs, I can’t.

And the current drop-down is much, much better.

Don’t fix what isn’t broken 😉 (perhaps you might want to actually focus on developing codeigniter)