organization of manual

[billehunt]

I highly recommend re-working the docs to organize and prioritize similar to how codeigniter does (http://codeigniter.com/user_guide/ - click on "Table of Contents" at top of page). Notes of things to emulate:

• flat: from the first page, you can jump immediately to every page in the manual.
• organized: toc is broken into several broad categories, each of which is immediately obvious in value (like "Installation", "Tutorial", "Class Reference", etc.)
• well-labeled: in the TOC, each page is also well-labeled, for example "Installation Instructions", "Controllers", "HTML Table Class", "Date Helper".
• the whole thing is searchable.

Problems with the current Lithium documentation organization:

• choice of categories
• number of categories that must be traversed to get to a page
• ordering of information
• lack of detail in the most important areas
• search is non-existant

Beginning on the very first page (http://lithify.me/docs):
On the left is "Libraries" as the header, then lithium, app, li3_docs, li3_bot, manual below it.

• What would a user expect to find under the "lithium" category? Isn't this the lithium site?
• what does "li3_docs" mean? Lithium is li3, so maybe li3_docs is the docs?
• what does "li3_bot" mean?
• what is the manual and why is it different from li3_docs?
  After a lot of probing, the user finds that the docs are actually in the last choice "manual". Since this is the "docs" section, all the other stuff should go elsewhere. I.e. clicking "docs" on the home page should go to the manual.

In the TOC of the manual, the sections are: Quickstart, Getting Started, Lithium Basics, Configuration, Writing Quality Code, Handling HTTP Requests, Working with Data, Authentication, Globalization, Extending Lithium, Lithium in the Cloud and Appendices. Of these, only "Quickstart" is intuitive.

Some specific examples of problems:

• "Getting Started" is another way of saying quickstart, but it's really the Installation section (So "Installation" is a better name.)
• "Lithium Basics" is badly named; it's really a combination of architecture, what's new, and aspect oriented programming. These aren't "basics"; these are things you may want to know after you get going. Also, the "architecture" section should be several sections, each in an appropriate category. (info on connections say in a data section; info on tests in say a test section, etc.)
• configuration section is good
• quality code: well, I'm all about that, but why is there more documentation on coding standards then there is on most of the basic functionality? And why haven't we gotten to the basic functionality yet? Bear in mind that because the TOC topics are so confusing, the whole doc is really one big serial doc. I.e. the early user really doesn't have a way to jump some place useful, so they read it one section after another (but having to dig 3 or 4 layers down to hit a page, then back up). So seeing coding standards before you understand details of building a controller is problematic.
• handling http requests: another advanced concept before we get to details of how basic functionality works. Same thing with routing. Only as a subsection of "handling http requests" are controllers, views and helpers introduced. These should be higher level and earlier. And since there's no search, hiding them beneath a name like "Handling HTTP Requests" is ugly.
  • Working with data is a reasonable name. I think I'd put "Using Data Sources" in more of an installation section, but that's a debatable point. The rest is good. maybe move "creating data sources" to an advanced section, but that's also debatable.
  • Globalization: I've never heard the term, and thought it might have something to do with global variables. recommend changing to the more standard "Internationalization"

[nateabele]

@billehunt Interesting thoughts, thanks for the detailed input. @Tomen Would it be possible to merge these notes with your existing outline in #11? /cc @raisinbread @Ciaro @meenie

[Tomen]

@nateabele @billehunt

I integrated this ticket as good as my time allowed for now. I compacted some things, rephrased others. The most specific part i didn't look at right now (the really detailed points at the bottom of this ticket. I suggest that @billehunt looks at #11 and tells me if i did not reflect one of his ideas enough so that i can flesh the respective parts out.

[billehunt]

Thanks, @nateabele @Tomen

[Tomen]

i suggest to close this issue and continue the discussion on #11

[nateabele]

Closing this issue to consolidate discussion on #11 (it'll still be linked from there for reference). @billehunt Thanks again for taking the time to provide such detailed feedback.