This is a combination of several inputs to improve the manual.
Some general problems identified in the manual:
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.
Hey, thanks for your feedback, @Tomen. Lots of great ideas here. @raisinbread, thoughts on the above?
This looks pretty decent to me.
Yeah, I think I like this, too, though I have a few comments:
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.
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.
Lithium Design => Lithium Architecture
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).
Outside the Box
I also agree with @Ciaro above.
What do you think?
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.
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.
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.)
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).
I agree with daschl, configuration before MVC. As for the proposed structure, it looks great :).
One last thing though, maybe have a section on Error Handling under Common Tasks. Just something with regards to setting up the ErrorHandler.
@meenie @raisinbread very good idea with that error handling part under common tasks. I'd second that!
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.
@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.
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:
Restructuring as per issue #11.