Thread

This topic is about http://codeigniter.com/nightly_user_guide
Screenshot: http://i.imgur.com/zJDcs.png
Table of Contents: http://i.imgur.com/WMl76.png

This topic is probably going to be about me ranting about the new documentation, but hopefully this will also be a place where the authors of the new documentation can enlighten me/us about the reasons behind the new documentation and its content/layout.

I puked.
I’m not sure if it’s because of the ugly blue bar or if it’s the blue “Source Code” link on top of a brown background, or if it’s because of the horrible Search button with a bad bad bad background gradient/effect or if it’s because the button itself is larger than the input field or if it’s because of the fact that the search still brings you to Google which isn’t able to categorize the subpages properly or if it’s because of the ToC being in the breadcrumbs or if it’s because of the ToC actually having a slow and oversized rollover effect with no headers or sections in it or if it’s because…
... well I could actually go on from here, but I’m not going to, however don’t refrain from adding to the list.

RST… Python?
Correct me if I’m wrong, but has the Reactor team has decided to force the users to download and install Python and what not in order to be able to have a local copy of the documentation which you must compile yourself?
Are you going to provide a HTML version for the users?

I’m still facepalming and because of that, I’ve forgotten most of the things I’d like to say about this new “product” of yours, but really… is this a joke?

I just did the dishes instead of further exploring the new user guide, I really hate doing the dishes…

And before anyone adds either of the following to the topic:
“But this is just the initial push” or “It will get better eventually”

Maybe you should have thought of that before releasing an official news post about it and maybe wait until you had a final product with whatever intention you have with it.

No sane person likes what they’re seeing in its current state.

They only happy person will be my gf when she’ll come home to find out I finally did the dishes ;p

Overall, I have to agree with Dennis.

1) The “new” style is not very functional. “blue” text traditionally signified a hyperlink…
2) The TOC is harder to use that the previous pulldown. I liked seeing all choices on one window.
3) The blue title text displays a “paragraph” symbol at the end of the text whenever I mouseover the line (this is a glitch!)
4) I’d like a menu of options, not the breadcrumb.
5) The “breadcrumb” does not work correctly. It shows “< notitle >” within the crumb string when I used the TOC to select “Handling Multiple Environments”.
6) The color style used to highlight code blocks (I think it is named “highlight-ci”) is far too light (lacking contrast). It is hard to read.
7) Implement an internal search engine, not google(r). This needs to be portable.

  Please, rethink this design…

And what happened to “user comments”?  I built a CI app version of the UG with user comments and a database. It is not such a difficult feature to implement, and would be immensely helpful.
Dave

3) The blue title text displays a “paragraph” symbol at the end of the text whenever I mouseover the line (this is a glitch!)

I don’t think it’s a glitch. If you hover over the paragraph symbol, you can see the anchor associated with that heading. IIRC, Wikipedia used to do this so you could link directly to a specific portion of an article.

That said…I think I just threw up in my mouth a little. The blue everything and maroon header (which I feel is a very necessary part of the CodeIgniter brand) clash very, very badly. Not to mention most (if not all) of the above complaints.

Haha, this “new user guide”, good one! April Fools is not for a while. You almost had me though…

Next you are going to tell me documentation will be converted to man pages.

This is bullshit I’m with you Dennis. Damn CodeIgniter always had a well made user-guide and now this. bah! I was translating all the pages to portuguese from portugal, now what when this become standard I should migrate to the new template?

Hopefully my earlier news post will dispel some of the FUD, but I’m happy to answer or clarify anything I can.

I was translating all the pages to portuguese from portugal, now what when this become standard I should migrate to the new template?

Multiple languages and translations are far easier to handle with Sphinx than with hand-rolled HTML.

Hopefully my earlier news post will dispel some of the FUD, but I’m happy to answer or clarify anything I can.

That dispels some of the U, but I’m afraid the F and D remain.

I understand the need for a better system as the source of the documentation, having written lots of documentation in HTML, I agree it’s a nightmare. Whether the system of choice be sphinx or a typewriter, as a user of the product (and it’s documentation) I don’t really care.

What I do care about it that the documentation should be usable. An that means on my netbook, in the airport, waiting for my shuttle to arrive. Sphinx and python installations don’t live on my netbook, and probably never will.

WanWizard, you never have to install python or compile any documentation for it to be useable.  You don’t even have to install sphinx on your machine to contribute and edit or write new documentation.  EllisLab staff who are command line phobic do it without problem.  Have you opened them and examined the source files?  ReStructured Text files are quite legible without any renderer.

Creating Language Files
=======================

Language files must be named with _lang.php as the file extension. For
example, let's say you want to create a file containing error messages.
You might name it: error_lang.php

Within the file you will assign each line of text to an array called
$lang with this prototype::

 $lang['language_key'] = "The actual message to be shown";

.. note:: It's a good practice to use a common prefix for all messages
 in a given file to avoid collisions with similarly named items in other
 files. For example, if you are creating error messages you might prefix
 them with error\_

::

 $lang['error_email_missing'] = "You must submit an email address";
 $lang['error_url_missing'] = "You must submit a URL";
 $lang['error_username_missing'] = "You must submit a username";

vs.

<h2>Creating Language Files</h2>

<p>Language files must be named with <kbd>_lang.php</kbd> as the file extension.  For example, let's say you want to create a file<br />
containing error messages.  You might name it:  <kbd>error_lang.php</kbd></p>

<p>Within the file you will assign each line of text to an array called <var>$lang</var> with this prototype:</p>

<p><code>$lang['language_key'] = "The actual message to be shown";

Note: It's a good practice to use a common prefix for all messages in a given file to avoid collisions with
similarly named items in other files. For example, if you are creating error messages you might prefix them with <var>error_</var>

$lang['<var>error</var>_email_missing'] = "You must submit an email address";</p> <p>$lang['<var>error</var>_url_missing'] = "You must submit a URL";</p> <p>$lang['<var>error</var>_username_missing'] = "You must submit a username";</code>

And yes, of course, HTML is our primary delivery format, and will always be available without having to generate your own.

I think that the new html is better if you’re browsing the guide in a panel of your IDE or on small-screen device. But I think you still need to divide the nav into sections like before.

And before anyone adds either of the following to the topic:
“But this is just the initial push” or “It will get better eventually”

Maybe you should have thought of that before releasing an official news post about it and maybe wait until you had a final product with whatever intention you have with it.

No sane person likes what they’re seeing in its current state.

But Dennis, it’s true that this is just the initial push. That’s important, and it sounds like you just wrote it off. Because by that, we don’t mean, “This is the first release, it’ll get better.” We mean that it’s literally the first push to the “develop” branch of our Open Source framework. We haven’t assigned a version number to it yet because it’s not part of an official release. This is Open Source, so it’s going to be developed in the open. You’re going to see the good, the bad, and the ugly of the entire source code if you watch closely enough.

We wrote a little news post about it to keep the community in the loop on things. It started with a simple tweet to say, “Hey everyone, check out what we’re working on!” The community has been pretty vocal about wanting to see progress on CI’s development, so we wanted to give a sneak peek. There was some major FUD on Twitter, so we decided it would be a good idea to expand on things a bit in a news post. It’s still meant to inform the community about how CodeIgniter’s development is progressing. It’s not an announcement of a CI release.

We definitely want your feedback on all of it, so feel free to give us your opinions. But don’t worry so much with how it looks. The bigger news here is what we’re doing with Sphinx to help build the User Guide moving forward. It’s a huge leap in progress because of all that it makes possible.

I wasn’t happy that the old user_guide had been removed.  I think at the very least, a ‘make html’ version of the user guide should be created for us too.  I completely understand and applaud the move to a format much easier to manage.  I already had python 2.7 installed on my macbook and using mac ports I installed sphinx (there was no mac ports for easy_install).  I tried to build it but I don’t have a sphinx-build, so it complained.  I did have a sphinx-build-2.7 on my system after the mac ports install.  I gave up about here, and wasn’t able to see the new user_guide so in my environment it’ll be a bit longer than 5 minutes to get it up and running.

I didn’t realize James Mathias was on board.  I’m a fan of his design work and I have confidence he’ll create something fantastic.

Edit: in my case, was able to figure it out.  I used ‘pip’ (pip-2.7, available with mac ports) to install sphinxcontrib-phpdomain, and ran ‘make html SPHINXBUILD=sphinx-build-2.7’ to get it to compile.  Looks good, will just take some getting used to the difference to know where to find everything.