How I learn things

[andrewducker]

I learn by doing.

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.

Comments

[birguslatro]

That there's money in computer games probably has something to do with why they understand how people learn. It's in their interests to get it right.

Compare with the rewards for writing open-source software.

[akicif.livejournal.com]

Thanks indeed for the heads-up on this. The next version of the Shibboleth IdP software will be using Velocity Templates instead of JSP for customised login pages etc...

[channelpenguin.livejournal.com]

I was actually talking about this sort of thing last night. I personally, for a non-physical task, pretty much head straight for abstraction. I am totally comfortable there and don't care about using symbols or even no name or label whatsoever in thinking about things (mentally, that "nameless" mode is kinda like... oh so if I do "this" [complex mental image] to "that" [another mental construct] , add a few of "those"... etc. - and that's really not explaining it very well at all!)

e.g. I learned set theory before I took up databases - and I do think it helped (and continues to help) me avoid some common pitfalls (but don't actually ask me to hold forth on set theory 20-odd years later!)

BUT... I am aware that most people are much more concrete thinkers who need concrete examples upfront, and that names matter - which is why I have to really concentrate and think if I want to teach or explain.

[steer.livejournal.com]

I prefer to know both the abstract and the "how to". If I only want to work with something for a bit then a simple how to and examples is fine. However, if I need to produce something of quality using a codebase I need the abstract because without that my code becomes a bunch of increasily ghastly workarounds from modifying the examples provided.

I suspect the reason for the documentation you describe is not that the writers don't "get it" but that they simply don't have time. While we all know that documentation is important, given limited time, poor documentation of working code is better than great documentation of non-working code.