Restructure english manual

[Tomen]

This is a combination of several inputs to improve the manual.

Some general problems identified in the manual:

• Choice of categories/Ordering of concepts - Concepts are introduced in a fashion that did not correlate to my(Tomen's) learning curve. There is some jumping back and forth to understand everything. Others have suggested, that some categories are not focused enough, badly named or that they could be ordered better.
• Number of categories that must be traversed to get to a page
• Lack of detail in the most important areas
• Search is non-existant
• Redundancy: Concepts that are exclusive to lithium are explained on a lot of occasions. Filtering for example is used in unrelated sections where a filter is just used. This is to make sure that everyone gets the concept, but a simple link would be sufficient.

Overhaul of the general structure/flow:

Basically, i suggest to restructure the manual to give it some sort of onion structure: You first have some easy and basic parts in the beginning, like Quickstart and Getting started. I suggest to merge Configuration chapter into Getting started, since both are about getting Lithium to run in the first place.

Then we move on to the core Lithium concepts, like MVC, Request/Reponse-cycle, Filtering and stuff, wich i would like to put in a chapter named Lithium design. This chapter is for all abstract content.

Then for actually using Lithium, there are the chapters Basic tasks and Advanced tasks. Basic tasks covers everyday tasks in lithium, while Advanced tasks covers topics not everyone may be interested in.

This structure would reduce the number of top-level chapters and ease understanding of where to look up what.

• Quickstart
• Getting Started
  • Requirements
  • PHP
  • Servers
  • Install Lithium
  • Connections
  • Troubleshooting
  • FAQ
• Basic Tasks
  • Create an action (Practical overview over MVC)
  • Working with views
  • Working with controllers
  • Working with models
    • Using data sources
    • Using models
    • Validation
    • Relationships
    • Adding Functionality to models
    • Creating data sources
  • Add a route
  • Add user authentication
  • Globalization (alternatively: Internationalization)
• Lithium Design ( Feature overview: merge all the cool PHP 5.3 marketing into this)
  • File structure
    • Webroot
    • Resources
  • Config
    • Bootstrapping
    • Connections
    • Routes
  • Object
  • MVC
  • Request/Response cycle
    • Overview
    • Controllers
    • Views
    • Helpers
  • Filters
  • Libraries
  • Extensions
  • Quality Code
    • Coding Standards
    • QA: static code analysis
    • Unit Testing
• Advanced Tasks
  • Create a Plugin
  • Use third party libraries
  • Lithium in the cloud
  • Using Lithium in other applications

Other issues:

• The landing page http://lithify.me/docs contains the four categories lithium, li3_docs, li3_bot, manual. This can confuse new users who actually want to read the manual. A first step could be to make the manual appear on top, have it selected by default and comment on the reference chapters what they stand for (doc-plugin, bot-plugin, lithium-core)
• The comlete TOC should be displayed, so that the user can jump into every section at every moment.
• For buckets of good karma, implement search

[nateabele]

Hey, thanks for your feedback, @Tomen. Lots of great ideas here. @raisinbread, thoughts on the above?

[jperras]

This looks pretty decent to me. 👍

[raisinbread]

Yeah, I think I like this, too, though I have a few comments:

1. Seems like we have MVC in three places: I think I'd just move the current response cycle stuff into the the "Basic" track.
2. The section on quality seems a bit misplaced, though I don't have any brilliant ideas on where to place it. It feels like an "Advanced" topic, but it really shouldn't be. :)

[Tomen]

@raisinbread:

ad 1: I agree. It's common enough that it should be sufficient to just mention it in an architecture overview and link to the "Basic Tasks" section of it for the concrete implementation.

ad 2: I had exactly the same thought! My argument for keeping it in "Lithium Design" would be that it belongs to the culture of Lithium Design. Also, while it is a topic that you have to get a sense for over time, this is also true for filters and stuff. You won't get the concept from the very beginning (and you also don't HAVE to, in order to get working software) but it will help. I consider the "Lithium Design" chapter to be something you don't read from beginning to end, but should know it exists and you can come back to when you are ready for the good stuff =)

Taking your feedback, i will begin with some incremental updates each accompanied by a pull request.

[raisinbread]

I talked with @gwoo yesterday, and I wonder if we can make the Design, Basic and Advanced parts of the tree empty (as in content) and also always expanded. I do like the grouping, but the drawback is that things will get buried if we can treat these nodes as a "unit" of sorts, and always have them expanded, that might be the both of best worlds.

Thoughts?

[Ciaro]

Lithium Design => Lithium Architecture

[meenie]

I'm not too sure about the chapters Basic Tasks and Advanced Tasks because there is nothing basic about Lithium and those Advanced Tasks are really no more advanced than some of the articles under Basic Tasks. I'd suggest calling them Basic Tasks -> Common Tasks and Advanced Tasks -> Outside the Box (still thinking about this).

I also agree with @Ciaro above.

What do you think?

[billehunt]

I like the proposed organization with the addition of moving "basic tasks" before "lithium design". The most important first sections are (in this order): quickstart, installation, basic tasks. With just those three sections, a first time reader should be able to get a good basic app going. Everything else is advanced.

Agree with all the above comments, except @meenie suggestion of calling sections "common tasks" and "outside the box". One of the biggest problems with the current docs are section names that aren't intuitive. "common is not bad, but not as good as basic, and "outside the box" is particularly un-meaningful.

Also, I believe we should not take the tack that "there's nothing basic about Lithium". PHP is about as basic a language as there is. MVC is about as basic a framework as there is. If Lithium is going out of it's way to be complex, that's a mistake. And if the docs take that direction, that's also a mistake. Simplicity is everyone's friend, and should be our goal, not something we avoid on purpose.

[Tomen]

@billehunt
I now did move the "basic tasks" before "lithium design". This feels right. Also, it moves "lithium design" and "advanced tasks" closer together, which also feels like a good move.

[raisinbread]

Getting ready to take a stab at this again soon. I've tried to consolidate ideas from the three or so issues that reference this, plus my own take, plus filling it out in places that seemed thin (or items just weren't covered.)

• Installation
  • Requirements
  • Installing
  • Configuration (minimal)
  • Troubleshooting
• Quickstart
  • Blog Tutorial
  • Another?
• Design Principles
  • MVC
  • AOP
• Models
  • Connections
  • Using Models
  • Entities & Collections
  • Adding Functionality
  • Model Schema
  • Relationships
  • Using & Creating Data Sources
  • Validation
• Controllers
  • Actions
  • Parameters
  • Routes
  • Flow Control
  • Exceptions and Errors
  • Type Rendering & Detection
• Views
  • View Variables
  • Auto Escaping
  • Layouts
  • Elements
  • Helpers
  • PagesController
• Configuration
  • Bootstrapping
  • Libraries
• Quality Code
  • Coding Standards
  • Static Code Analysis
  • Unit Testing
• Common Tasks
  • Debugging
  • Logging
  • Caching
  • Console Applications
  • Basic Filtering
  • Authentication
  • Globalization
  • Extending Lithium
  • Plugins
• Advanced Tasks
  • HTTP Services
  • Adaptable
  • Dependency Injection
  • Lithium in the Cloud
  • The Response Lifecycle
  • Advanced Filtering
  • Lithium Object Architecture
• Appendices
  • Launch checklist
  • FAQ
  • Li3 in Other Apps

[daschl]

I really like this structure, but what about moving configuration before MVC? I normally need to configure my system before I can start developing (and we have the quickstart part before it anyway).

[meenie]

I agree with daschl, configuration before MVC. As for the proposed structure, it looks great :).

[meenie]

One last thing though, maybe have a section on Error Handling under Common Tasks. Just something with regards to setting up the ErrorHandler.

[daschl]

@meenie @raisinbread very good idea with that error handling part under common tasks. I'd second that!

[raisinbread]

So the tricky thing about config is that it I believe it should really get handled in other sections where it has better context. For example, talking about connections in the Models section. I did want to touch on it to give people a sense on how we do it and how things are put together, but too much focus on it by itself didn't seem optimal.

I've actually purposefully placed a bit of mention about config in the first section just to get people up and going, and I do plan on touching on relevant config as we move though, too.

Having said that, do you still feel I should move it? I do like having them jump right into the Ms Vs and Cs. :)

Great point on the Error Handling—I'll add that.

[nateabele]

@raisinbread I tend to agree with moving the config section before MVC, but probably for slightly different reasons. Namely, I think understanding the bootstrap process structurally and conceptually is central to a practical understanding of how the framework operates on a practical level.

You don't need to go into detail on everything that's included in the default bootstrap, just explain about how we have a general pattern for provisioning external resources, for configuring and connecting different classes, and that the bootstrap process is just a series of simple procedural scripts.

[raffishquartan]

Broadly broadly, I like this a lot, especially, the MCV flow (makes sense!) and the Common Tasks/Advanced Tasks.

Re: Position of Configuration vs Position of MVC: I agree with Nate that an upfront, conceptual explanation of how the bootstrap works is important. This might not be the kind of configuration you mention under "Installation", but maybe it is? If not and it won't fit there, could it be added to the "Design Principles" section?

In any case, a detailed explanation of user/external libraries and how to use them would be really useful, and I agree with its current position.

Two additional things it might be useful to include in the manual are:

• Links to the community: Add a section to the Appendices or the Quickstart pointing people to Stack Overflow, #li3, key blogs. This would help new users engage more with Lithium and see what other people have done. It would also be good to recognise some of the fantastic material that people have put up on the web!
• Code flow: It's quite difficult to follow the code flow through reading the code, and the filters and anonymous functions also make the stack trace pretty hard to decipher. To complement the existing text descriptions, it would be useful to add a set of UML sequence or application flow diagrams.