My Gripes With Technical Writing.
My previous blog was all about technical writing. As a young and budding developer; some of the posts out there were aimed at talking about the latest cutting edge technology; flexing my engineering mussel and getting more traffic out of Google.
As I wrote the posts however; I realized that; unless you are talking about the products you are yourself involved in; technical writing is harder than any other forms of writing.
Unless you genuinely believe in the craft of story-telling; the life-cycle of writing a technical post pretty much goes like this: You take a topic; you dissect it; you understand everything there is too understand about it and then you try to pass that understanding over to your readers. It was almost like taking a traditional approach to teaching.
After a while; I realized that there was one word that describes this entire process: Boring.
Don't get me wrong; dear reader. The mere act of writing code or reading it isn't boring. It gets you in the flow and does amazing things to your life. Having said that; the very process of writing about code; or reading about it; is in fact very boring; and there are multiple reasons; dear reader; why this is the case.
I'm going to make a humble attempt at touching some of these reasons and try to figure out why most technical articles or books out there are unable to keep my attention span end-to-end.
Ready?
Let's get started with my gripes on technical writing.
Technical Writing is Based On Facts.
Let's face it; the way most technical writers of today write; Dependency Injection is basically --- dependency injection. That's where most technical writers of today start and stop. Take the Wikipedia definition of dependency injection; for instance. Here is how it goes:
Dependency injection (DI) in computer programming refers to the process of supplying an external dependency to a software component. It is a specific form of inversion of control where the concern being inverted is the process of obtaining the needed dependency. The term was first coined by Martin Fowler to more clearly describe the mechanism.
The very first sentence is a turn off. By the time you near the end of the article; you can hear yourself snoring out loud.
It isn't Wikipedia's fault though.
What Wikipedia is doing; dear reader; is capturing facts and presenting them to you. This is what most other technical writers writing technical books seem to be doing. Most of them; seem to base their books or their writing around facts; and the inherent problem with this approach; dear reader; is that facts; are boring.
Lack Of Spice And Information Surrounding The Content.
Pick a few basic books on neuroscience and they will tell you a great deal about how our brain stores and interacts with information. Neuroscientists; around the world; up-till the recent times believed that information in the human brain is stored in a central location and that lesser the information the easier it is to commit and recall.
Recent opinions however; seem to suggest that information in the human brain is basically stored all over the place; and the human brain uses the 'context' to get you a faster recall. Long story short; dear reader; spice and some amount of irrelevant information; connected with the fact is just as important as the fact itself.
I first understood the importance of this brain-rule during my French-classes.
To illustrate my point; dear reader - I am going to teach you some French.
Ready?
The French word for 'who' is 'qui' - I want you to commit this to your memory - get on with your life and do a recall a couple of months later.
Now; if you are like most of us; chances are that a couple of months later; as you move on with your life you are going to forget this piece of information all-together.
Now; do this - turn the literal fact - "who in English equals qui in French" - into a tiny little sentence with some useless information and some context.
Put simply; just try and remember the English sentence - 'who has the key'.
Now; given that the pronunciation of key and qui are exactly the same; months later; when I ask you the French translation of 'who' - chances are; that you will not just remember the French translation; but you might actually have a faster recall.
Ok; back to technical books on programming. The problem with most technical books today; is that they lack this additional spice and information that is supposed to make it easier for people to remember the facts that the book is presenting.
When it comes to technical writing and reading about code; less is not more. In fact; neuroscientists around the world will tell you that when it comes to storing information about a fact; the more random connected information you have about the fact; the higher your chances of remembering that fact are.
Now; look around. Take a look at all the technical books you have. Also take a look at all the technical blogs that you can find online. How many of them give you this additional information connected with the facts they present? How many of them provide you with additional; hugely interesting information that helps you commit and recall the stuff; faster?
Thought so.
This Thing Is Supposed Be Fun.
I've known some amazing fun loving authors and have had the pleasure with observing them or even remotely working with them. These are seriously fun loving guys who can take a concept and drill it into your head by the time you are done with your lunch with them.
However; when they indulge in the act of technical writing; you somehow seem to get a sense that you are reading a completely different individual all together. Pick their books and you will realize that the sense of humor is gone; the jokes are gone; the funny analogies are gone.
What remains is a me-too book or a me-too programming blog on C# or Ruby On Rails that other C# or Ruby On Rails programmers go to.
Over years; our technical writers and authors around the world seem to have nurtured the thought that a technical book ought to be something 'serious' and 'professional' and therefore it is completely inappropriate to go out and experiment when you are writing a technical book or a technical blog-post. That dear reader; makes most technical books and blogs out there nothing more than material that you reference when you are stuck with a problem.
When was the last time you picked up a book on Design Patterns and had 'fun' reading it?
When was the last time you giggled while reading a book on C# programming?
When was the last time you had a deep realization that triggered a chain of thoughts while reading the explanation behind a code-snippet?
Technical Writing Lacks Persona.
Every book; be it a novel; or book about software development; reflects the author's personality. Most technical books out there however; don't.
We have seen the use of F-word; in books and blogs that are connected to software development.
We have seen management books use words like Asshole.
We have seen books on organizations and entrepreneurship which move and inspire.
The idea is not just to grab the attention of readers with purple-cow words; but to leave a little bit of your daily-persona into the book when you are writing it.
While it is true that no-one cares about you or your product; it is also true that there is a little bit of you in everything that you do and that little-bit-of-you makes everything you do different. Most technical writers however; seem to miss out on putting in a little bit of their personality into their technical writing.
We are Taking It Way Too Seriously.
There are over two hundred blogs that I subscribe too. The ones I love the most are blogs where authors take chances; post something that is wrong; learn from their comments and then go out there and change with time.
While the whole idea that authorship does not mean authority seems like a well known fact in blogs that do not talk about code; the ones that do; still seem to be a little hesitant at being opinionated; passing on their own thoughts and insights about the code they are explaining and making blatant mistakes while they do that.
As a matter of fact; most authors seem to take the easy-safe-boring way out; which is to eliminate this information all together.
As authors and programmers are we taking what we write or read; way too seriously?
Are we missing out on all the fun connected with making mistakes and learning from these mistakes?
After all; there is something to be said about learning with a mind of a child.
As I slowly start nearing the end of my first book and as I find more time to fly-free; every 'once-in-a-while'; I plan on working on an article or two that touches code; programming techniques and even design approaches; to see if I can add a little bit of myself to my technical writing.
The idea; dear reader; is to introduce you to my very own personal code persona that has it's very own approach to dissecting and trying to understand code; programming techniques; and information pertaining to improving your programming skills that is freely available out there.
Maybe; I'll make a fool of myself; maybe the articles will not be 'technical enough' for a few hardcore programmers out there. Maybe they may not fetch me all the Google traffic that my older blog used to fetch me; but I am going to go ahead and give it an honest shot anyways.
If you are a programmer at heart; you should too.
Go add a little bit of spice; fun and yourself to every seriously technical post that you are about to publish on your blog.
I dare you.
Small aside: If there is a book or technical blog out there that you know of; which goes deep into programming; code and design in a way that is fun; if you know a book or a technical blog that has an interesting persona of its own; I would love to read it. If its a blog I would love to subscribe to it. Go ahead; drop me a comment; or send me an email.
Comments are closed.