Home > SD in general > RTFM!!


As a follow-up of sorts to a previous blog, I’m going to rant a bit now about the situation that there is decent documentation, but people refuse to read it.

In ye’ olden days, I have tried to study books like this as part of my Master’s studies in Mathematics, books which are really hard because they deal with very abstract topics and do so in a comprehensive but still quite compact manner so you have to ’embellish’ the reasoning by interpolating between the factual statements given in order for you, mere mortal, to be able to understand it completely.

And by ‘hard’ I mean ‘time consuming’ as much as ‘headache-inducing’, the juxtaposition of which precludes that “Googling for 5 hours” will get you anywhere: it may be time consuming (it certainly is) and might be ‘frustration-inducing’ but your brain is not engaged enough by that type of effort to actually attain a bit of knowledge about something from which you can come up with a solution to your problem. It also precludes finding solution for problems which nobody ever encountered before or which have been worded sufficiently different.

Going back to math books: I always told the (business/psychology/A.I.) students I had while being a student assistant teacher, that if they worked their way through one page of mathematics in less than a quarter of an hour, they could be 100% certain that they hadn’t understand one bit of it and would therefore fail their examinations. I’ve never been challenged about the truth of that statement, only the minimum amount of time varies per student and per book/course: usually it takes a lot more than 15 minutes to really grok the material. For the book I cited earlier, I could substitute ’15 minutes’ with ‘8 hours’. In the end, I’ve given up on that particular book. Luckily, that didn’t stop me from getting my MSc.

The reason that learning takes time is that the human brain is surprisingly good at a great number of things, but remembering factual statements rigorously and executing their semantics in a totally reliable manner isn’t one of them. I read once that “the human brain is very good at avoiding being eaten by a mountain lion and distinguishing the nourishing berries from the poisonous ones, but we aren’t that well equipped for thinking about 11-dimensional spaces”. We are exceedingly good at pattern recognition and are able to deal with incomplete or faulty ‘input’ very well -ftr ll, y cn prbbly rd ths sntnc jst fn- but logical thought takes a bit of a backseat, comparatively speaking.

To do ‘intellectual stuff’ like reasoning about parser implementations and such, we have to build up a sort of mental model which we can hold in our brains. This mental model holds all sort of knowledge: both factual knowledge, remembered verbatim, but also vague stuff which we could file under ‘intuition’, as well ‘executive knowledge’ which can be fed input and which helps you form thought processes. All this will hopefully enable you to solve problems; if not, you have to adapt and expand the mental model. The mental model is unique for each combination of a particular human brain and a particular domain and not readily expressed in any natural language, which also explains for a bit why teaching is such an art: you have to find a modus to tap into the brain and the relevant mental model of the people you’re teaching.

(Disclaimer to the previous paragraphs: I’m not a psychologist nor a neurologist, so what I’m saying here is essentially my mental model of how learning works.)

Building up the mental model takes time, and appreciably more time than just reading some text book: your brain has got to remember a lot of ‘stuff’, make connections between that stuff and validate all new inputs (the next sentence) against the mental model that’s being formed. And to add insult to injury: often enough it’s very difficult to say that your mental model has actually expanded at the end of the day, because once you really understand something, it tends to become trivial and the mental model feels ‘compressed’.

I realize that I have yet to start my rant for real…

In stark contrast to the former, this day and age apparently is one where all answers should be one Google search away. This is unrealistic for many reasons, the most important being that it would imply that all answers are already known, which would be a depressing thought in itself. However, the most demeaning aspect of this school of ‘thought’ (or lack thereof) is that it is implied that knowledge is unnecessary and that only facts matter. But facts in itself are essentially inert matter and you have to make it come alive by embedding in a body of knowledge: a.k.a. the mental model. Without that we would be the proverbial infinite amount of monkeys hammering away at typewriters to try and come up with a Shakespeare play.

Also annoying to the max is the idea that communities (such as the plethora of Eclipse fora) exist to do the work for you, rather than helping you do it by guiding you in acquiring more knowledge on the subject. It seems that home schoolwork is often done these days by posting the problems to some Q&A site and expecting, nay, demanding that someone else solve these for them. Instead of being glad that someone who has already gone to the trouble to attain the knowledge required for performing that task free up some of his/her time to try and help a complete stranger by giving hinters, tips and useful pointers, abuse seems to be in order…

For myself, I’ve decided already some time ago to only help those people who show at least some willingness to learn and put in the (right kind of) effort themselves. In fact, I tend to try and help everyone but stop helping as soon as my help isn’t taken seriously, no effort is being expended by the other party, I receive abuse or any combination thereof – there’s no point in feeding the troll, after all: he/she can go gnaw some rocks, as far as I’m concerned…


Funny point in case: how to post on xda.

Categories: SD in general
  1. December 1, 2011 at 12:05 pm

    Expect others to invest no more time in solving your problems than you’ve invested yourself.

    • December 1, 2011 at 12:08 pm

      Damn, and I needed 1040 words to say the same thing! 😉

  2. Hallvard Trætteberg
    December 1, 2011 at 3:13 pm

    Another variant is: Don’t expect a person/system to be more helpful than you are. If you don’t really explain your problem, e.g. just say that ‘it didn’t work’, you shouldn’t expect to get help.

    A student asked for help recently, he tried to create a dynamic instance of an Ecore class and an error dialog for a NPE popped up. It turned out an attribute lacked a type and he hadn’t validated his model. But why couldn’t the system give a more helpful message, he replied… he expected the system to try harder than he did.

    • December 3, 2011 at 3:47 pm

      Oh so true as well. Moreover, by taking care to explain your problem properly, you’ll find that you can answer it yourself after all in a fair number of cases.

  3. December 7, 2011 at 11:32 pm

    When reading your previous blog (a valid story btw) I was reminded by a specific case. I had been working for a client that required a complex solution for authorization of the new service we were building for them. We had to tie-up the existing authentication solutions (SSO and ip-filtering) with a new payment-based authorization scheme. As our solution existed of different web-components (web site, web service, web shop) that each needed to understand the authorization, I knew the federation of authorization was a difficult part of the architecture and I took care of documenting this really well.

    After I left the company, I got called a few times by engineers maintaining the solution, asking about this specific part. I explained them how it worked but asked: “Isn’t this documented properly on the agreed place?”. The answer consistently was: “well, sure, possibly, I never bothered to read it because it’s so much easier to ask someone who knows and can explain it.”

    This is a lot of words for: having access to someone with experience (and willing to explain) is so much better than reading and learning by yourself. Agile teams exploit this by focussing on knowledge sharing by cooperation over documentation. This experience changed the way I think about the complaint of “too little documentation” from people that take over the maintenance of some new code base. It’s always true and if it isn’t; you wouldn’t bother reading it anyway 🙂

  1. January 2, 2012 at 11:10 am

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s

%d bloggers like this: