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
- To answer the question directly
- 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.
- A microservice is a web service
- LESS is a way of writing stylesheets
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 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?"
- A method of asynchronous client-server communications possible over most messaging protocols, though most commonly HTTP.
- A mechanism to send requests asynchronously for information to a web server typically as JSON or XML and expect a response back in the same format.
- A way for a web page or application to talk to a server and get information without having to refresh the page and disturb the user.
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.
- Polymer is rebuilt from the ground up for speed and efficiency. The new, leaner core library makes it easier than ever to make fast, beautiful, and interoperable web components. So that's not helpful. I still don't know what it is. What it does, maybe but only by implication.
- Simple.Data is a lightweight framework that uses the dynamic features of .NET 4 to provide an expressive, ORM-ish way of accessing and manipulating data without any of the code pre-generation and boilerplate required by other frameworks. So if I know enough jargon I can imply what it does, but what does ORM-ish mean? What code pre-generation and boilerplate? This definition strays into "specialized knowledge". (Worse still, I wrote it a few years ago and no-one has changed it since)
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.