Latest news about Bitcoin and all cryptocurrencies. Your daily crypto news habit.
Since Dec 26th 2009, I have written regularly on my personal blog theburningmonk.com on a variety of technical topics. Suffice to say that I have had a lot of practice of technical writing!
I love learning, and I love sharing. What I learn I like to share through writing, as it also helps me solidify my understanding too.
Over the last 3 months, my posts have received around 75K views per month across medium and my blog. So the evidence suggests that my writings arenât turning readers away at least!
So to help more people share their knowledge and insights, here are a few simple rules that I follow when IÂ write.
Mind the âcurse of expertiseâ
The most important rule of thumb is to always remember you are the expert of your domain. When you share knowledge & experience, you need to be mindful what assumptions youâre making of the reader.
Especially when you discuss the merits or problems of an approach. Always state your assumption and context explicitly up front. This helps the reader understand WHY youâre doing this, and the constraints youâre working with.
In the immortal words of Simon Sinek, start with why, which brings us to the next point.
Sell the problem, NOT the solution
Like that great scene in âthe wolf of wall streetâ where Di Caprio asked Jon Bernthal to sell him a pen.
Create the demand, then supply the solution.
Sell the problem to the reader. Help them understand why itâs a problem worth solving. The merits of your solution are irrelevant without an interesting and worthwhile problem.
Where possible I try to set out what a âgoodâ solution would look like, and what properties it should have. After describing the solution I would then finish off with the tradeoffs I have to make. This would usually evolve around the pillars of cost, complexity and efficiency.
If you donât define what âgoodâ is up front, then itâs easy for cognitive biases to creep in. We often subconsciously bend the definition of âgoodâ to fit our solution, and lose objectivity in the process. We all have this confirmation bias, thereâs no escaping it. But defining âgoodâ ahead of time helps keep us honest with ourselves.
Keep in mind that your solution might only work in specific contexts. If people adopt your solution without understanding the context in which it worked, then they risk failure. Worse yet, if the failures are not obvious enough, then you might have started another cargo cultâŠ
Keep it short
On medium, you can see how long your post takes to read and how many people read it start to end. Unsurprisingly there is a clear trend that longer posts have a lower read %.
I compiled the stats for my posts related to serverless and this is what IÂ see.
This is reflected in my personal reading habits too. I tend to finish longer posts over several sitting as I often lose my attention span midway. Iâm seldom able to finish a long post in one sitting, even if I âm really engaged by it.
What that means to you is that you should keep things short, punchy, and to the point. Donât linger with your words and try to explain things to the Nth degree.
If need be, use bullet points, and keep each to one line.
Write the post, then read it back a few times. With each run, cut out unnecessary words or rephrase sentences to make them more concise.
For example, âto be or not to be, that is the questionâ might be vague and leaves a lot to the reader. The longer, more expansive version is actually far less clear!
Courtesy of Kevlin Henneyâs talk â7 ineffective coding habits of many programmerââââhttps://www.slideshare.net/Kevlin/seven-ineffective-coding-habits-of-many-programmers
Be honest
Goes without saying :-P
Picture says a thousand words
Apply common sense, too many pictures is also not good.
Also, keep pictures relevant. We all love cat pictures, but too much of it (or used out-of-context) is off putting.
Start strong
I follow this advice when giving talks as well, and try to kick off a presentation or post with a strong message.
Think of your readerâs attention span as a currency. You have to earn the audienceâs attention before you can spend them on technical discussions.
Conclusions
So thatâs it, 6 simple rules that I follow whenever I write. The freecodecamp folks also have some very good advice for writing on medium.
I hope this post helps you improve your writing. If you have any suggestions on how I can improve my own writing style, please feel free to let me know via the comments below.
Happy Easter everyone!
here are my top tips on technical writing after 8 years and 700 posts was originally published in Hacker Noon on Medium, where people are continuing the conversation by highlighting and responding to this story.
Disclaimer
The views and opinions expressed in this article are solely those of the authors and do not reflect the views of Bitcoin Insider. Every investment and trading move involves risk - this is especially true for cryptocurrencies given their volatility. We strongly advise our readers to conduct their own research when making a decision.