About Links Archives Search Feed Albums of Note


Establishing the What

It appears to be late on Saturday night. I am prevaricating with a coffee cup half full of wine that I mistakenly poured in there without a great deal of thought. I suspect many future posts will also be written under such circumstances in the interests of switching my brain on before Sunday comes rather than off as it would prefer.

Hello from the top of Steepness hill.

Common wisdon would have it that the best place to start is always at the beginning. As any fan of David Lynch, that it not necessarily the case because the beginning is where you establish the big things. The what, the why and the how. This post is going to talk (meanderingly) about establishing the what.

“So what is it then?” comes the cry of the editor. And in response comes an assumed (as this conversation often happens on an audio only call) look of bafflement from the author who has spent many moons working with people who already know, a breath drawn in, and “Well…”

The truth is that there are two things to remember

  1. To answer the question directly 2. To whom you’re answering the question.

Let’s take a quick moment on each of these ideas

Answer the question directly A book that teaches is not a place for hubris or PR.

Bam!! And there’s the answer. Of course you can then drill into that definition but already the reader knows what ballpark we’re in. Web development, desktop apps, big data handling and so on. Or do they?

Who are you answering? I still subscribe to the idea that at least the first two pages of any tech book should pass the mum test - that any non-programmer should be able to read and follow those first two pages and tell me what they were about. There’s a great discipline in being able to do that well. And equally in remembering that any new reader is a lay person.

Vitorio Miliano [http://opendesign.foundation/articles/import-designers/] says it very well.

A lay person is “someone without specialized knowledge,” and that doesn’t mean only non-programmers. For you, a lay person is anyone who doesn’t already work on your project, even if they’re a programmer of some sort. Your project is the “specialized knowledge” in this case.

Consider these three answers to “What is a web service?”

If you can identify who you are answering and their level of knowledge, that should inform you how to answer the question. Can you accurately describe the technology  product  thing using terminology your reader is certain to know already? A definition is no good if your target audience then has to look up all the other words in the definition because they are “specialized knowledge”.

But doesn’t everyone already think about these two points when answering “What is it?” Sadly not. Go to chapter 1, page 1 of many books or to the front page of a project’s website and if they attempt to answer the question at all, it tends to be done by sliding around the answer so that you have to imply what it actually is. Let’s take a few examples from the web.

It’s not a great onus to remember these two rules when answering but it’s easy to get distracted by describing characteristics, features, or what you can do with something first and assume you’ve answered by implication. Try not to assume. That’s makes an ass out of u and me.

Posted on April 25, 2018   #Geek Stuff     #Writing  






← Next post    ·    Previous post →