Why documenting Feels Hard

Last night, I realised I wanted to write a blog post about why I’ve been posting so much recently. There are two reasons, FeedDemon is making it easy for me to read many feeds, and thus I think about stuff that I want to talk about. And I’m documenting what we should do. Aka design.

Now I know the value of documentation is fantastic, and it lets me off load thoughts, gather others input and refine the plan for what is coming. But what I find hard is the writing for three reasons.

  1. I am pretending to do something mentally, so I can review my thoughts, decisions and strategies. Then write all this goodness down. But pretending is not actually doing. So there is a feeling that it’s not real, in which case why do it. I know weird feedback loop.

  2. Then I start writing stuff, and I am dictating to myself what to write. The thinker part says some profound thought, the writer queues this and starts to interact with the typist, to get it written. The latter two are slowish, so the thinker

    1. waits
    2. races ahead (and this can inject false words or letters into the typing queue, and the output becomes confused, family members will recognise this outcome)
    3. goes off on tangents

some times the typist gets stuck and has to consult the speller, then the whole process stalls. Dangerous place to find ones self.

  1. The last reason I dislike writing is I’m not sure: I’m writing the correct thing? The right target audience? Too little information? Too much? Then analyst paralysis over what to write kicks in.

So I read blogs, write blogs, check email, write emails, eat lunch, then in the afternoon, in a fit of guilt make myself do the task at hand. Then I feel pleased progress is been made, but ashamed I didn’t start earlier. Because it’s not really hard, once you got it down others can add value and you feel good that you have advanced the good fight. But that is not how it feels at the start of the process.

So with this all in mind, this morning I read Mark Lawrence’s Why do I hate documenting Application Architectures? and felt doo-ee-oh, so just had to write this. Which was easy because I was just talking to myself.