Give me something _simple_ that works, and let me play with it.
Then add another simple thing to it, and let me play with that.
Slowly build up the different levels, until I have something that is functional, and useful.
I mention this, because I'm grappling with the Velocity template tool* at the moment. And the documentation is shit, and in a particularly strange way.
Firstly, the documentation isn't on the actual website. Which means that you can't have a three minute scan before you decide if it's what you want, you have to actually download it, unzip it, and then look in the docs folder. This is not a great start.
Then, when I start looking at the User Guide it works in _exactly_ the way I want - if you're the person writing the web pages. It does exactly what I want - start off with a simple "Hello World" example, and then build up from there into something useful.
It wasn't until I'd read that all the way through that I realised that it hadn't provided anything useful for setting it up in the first place. So I skip to the Developer Guide, and the first part is "The Fundamental Pattern". Except that that doesn't start me off with a "Hello World" example, but instead starts telling me what abstract steps I need to carry out, and then hits me with the choice of whether to use the Singleton Model or Seperate Instance.
And if you're baffled by that, then you're not alone. The people writing the documentation clearly think that the best way to learn is to feed you all of the abstract information about the design of the system up front, and then once you understand it all perfectly you'll be able to write whatever you want. And I just don't learn that way.
What frustrates me is that the way I learn is clearly not unusual. Every single computer game follows the model I laid out at the top. Learn a simple move/technique, use it to solve a problem. Learn a second technique, use it to solve another problem. Solve a problem that combines technique one and two at the same time. Learn a third technique, and so on.
I really don't understand why more people don't get it.
*Take some HTML, mix in some data, throw it at the browser. I didn't like JSP very much, because it has the code in the middle of the html, and I'd rather keep them separate if I can.
Original post on Dreamwidth - there are comments there.