Presentation guide for technical posts
Start adapting Inclusive Design concepts
The inspiration behind this post is from a Keynote talk by Soumya Subramanian at Google Developer Days India 2017. It’s about Inclusive Design and how it should be applied when creating a product. I’ll be explaining what it is in a while. But if you feel you need more information regarding this, please do check the video below. I’ll be talking less about inclusive design and more about applying those principles when you’re writing and publishing technical content at Medium or elsewhere.
Who should read?
This post if for all the tech bloggers out there. If you’re a great tech blogger with huge fan following or if you want to start writing blogs, well this is for you.
What is Inclusive Design?
A design is said to be inclusive when the particular product or service is applicable for all the people — who differ by gender, culture, geography, knowledge, colour, language, physical and mental challenges and so on.
A very good example, as mentioned in the video above, when there is a product to detect face and unlock something or taking a picture, it should work for all people. But it failed to work for people with darker skin tone — of course, the camera should absorb light to process but it should be working. To know more about this design concept, feel free to watch the video. It’s one of my favourite session.
What Inclusive Design has to do with writing technical content?
Good question! Let me quickly explain my background. I’m an Android developer cum UX designer (yes, a unicorn developer :-P). After learning the concepts of UX, I began to apply those principles in all the fields that I came across. I try to apply to Android every day to create good products. I recently applied UX principle to Marketing for a talk.
But Why in writing? I feel those concepts can be applied to writing as well and on researching further, I derived this guide.
Presentation Guide
This guide is derived by keeping your readers in mind. This is not a quick hack to increase your views or reads but a genuine way to make an impact with your thoughts to your readers and thereby your posts will grow organically
1. Start by telling why you write
Making a connection with your readers is very important and doing that initially is a great start. So, start by telling your users why you’re writing this post. What inspired you to share this knowledge. This will definitely bring them to the same page. This shouldn’t be long — yes, it depends on the type of post but when you’re writing technical content, keep it short and simple.
2. Who should read?
Who should read your posts? Yes, you will definitely add tags and stuff. But you really need to mention this to be more clear. Is it for the beginners? advanced? or anyone? or is it for people who experiment on something? any specific crowd you’re targeting? you need to mention who should read.
If the criteria match the readers, they will have some energy boost and you’ll definitely hear them saying “Yes! this is what I asked for” or “yes! that’s me”. This will bring some joy in reading.
3. Link to the series, if any
This section is optional i.e. when you’re writing a series of posts, you need to mention the user the link to start with. Also, the number of links in the entire series and where they are — Example
Also, if the post is in middle of the series, please do mention what happened in the previous series — just like a recap.
4. Prerequisites, must
This is an important heading and almost all great bloggers miss this. Here’s where inclusive design plays an important role. Your cluster of readers will involve everyone — beginners, intermediates, experts and so on. To filter them we have the step 2, which will focus on bringing the right people to the article.
For explanation purpose, let’s say intermediates are your target i.e. the following concept or example that you’re presenting is for them. But even some uncertainty is present among them when you compare the knowledge. Some might know the concept you’re trying to explain and some don’t.
So mention the prerequisites with links targeting to a simple tutorial on that. Example, in one of my article below, I’ve mentioned the prerequisites.
5. How many words?
It’s good to decide on the number of words that you’ll be writing. For a typical human capacity, 800 words are optimal. Also, your reader will not only be reading your post, he or she might be reading more. So it’s good to push your thought within 800 words. If you have no choice but to exceed, then please do mention that this post is long and ask them to book mark and read later.
I’ve gone few extra step and mentioned checkpoints, where the users can take a break and continue later. How? check the post below.
6. Never cut short the title
Yes, this is important as well. This is for the users, who skim or scan the posts. When some people who are looking on something, searching for many posts for a solution. You might have written it but to catch their attention, completing the title is very important.
Even for this post, many would just see the points on the fly. They will not be reading everything. For the tech post, everybody will scan through the title, code and diagram if any. So never cut short the title.
7. Marking tech keywords
If you’re using any tech words like Class name or something, please mark them like this. When you do this, the human mind will give more concentration to those words and also that will separate them with spoken language.
If you can’t mark it then at least try to make the bold, in italics or within “quotes”.
8. Use gits for codes
Use Github gists for displaying the codes. Don’t be lazy and use the native code block. Code presentation matters for your readers to read properly and Medium’s block is not providing the proper indentation.
Please don’t use this to present your code. Use it only for marking the keywords
User Github gits. It’s free to host. Make your code stand out and don’t be lazy!
9. Link keywords to source or to additional resource
When you’re trying to explain some concept within some concept, you will not be spending more time on the concept within concept as it is not the agenda. But please do provide them links to continue learning that nested concept.
Example — To understand the concept X, you need to know concept Y. Concept Y is nothing but blah blah blah blah (know more)
10. Use drawings, diagrams or Infographics to explain complex content
Infographics or diagrams will create better information retainment in the human brain. You can test this yourself.
Try to imagine a text or a paragraph from your childhood school books. Got one? Now try to imagine an image. I’m sure you would have a lot of pictures in your mind. — Hence proved :-P
If you feel it’s difficult to create, try using free tools like Canva or Google Drawings — it will help you to create charts and graphic content. Or you can also use many mindmap tools to deliver your thoughts easily.
11. Practise the art of storytelling
Storytelling is a wonderful art. Not convinced? well, do you know it’s the base for Marketing and sales? to make the users spend money or time, you need to give them a story to believe or a story to need.
In blogs, people are not spending money (they may) but they are spending something more valuable — their time. It’s your responsibility to value them and ensure that you deliver your thoughts and make them understand as well.
You may be a techie, you can still tell a story. Always have a story to explain the technical things. Make it such a way that even a non-techie can understand your story, then they can relate to your technical content.
Example, I’ve kept Game of Thrones as a base for this following article. Not a good story to choose but it worked.
12. Distraction-free reading
I’ve added my stories as an example. But some of them would add as recommended reading and so on. This distracts the user a lot and it does not deliver a good reading experience. It’s once again like reading with ads.
Instead, list it at the end. Readers will definitely check it out if in interests them.
13. ?
This can be your point too. I would like to keep it open for you. If you ever come across any difficulty in understanding a topic or if you feel something was missing in the content, tell me your UX story.
Write to hariutd@gmail.com, and I’ll definitely add your point here.
TL;DR
Guidelines
- Start by telling why you write. what inspired or motivated you?
- Tell your readers who this post is for.
- Let them know the prerequisites. Guide them in proper way
- Decide the number of words. If it’s more, make it like series
- Never cut short the title, even if it’s big
- Always mark the
techkeywords - Always use Gists than code blocks
- Link the keywords to additional resource
- Explain things with graphical content
- Practise the art of storytelling
- Create distraction-free reading
Final Thoughts
As I’ve mentioned earlier, you need to develop the a very important quality — Empathy for your readers. Vet your article once with your junior developers if you have or please send it to me, I’ll identify the experience issues for you :-D.
These guidelines are for the people, who want to share knowledge and also ensure that it reaches them properly.
So the question to ask yourself is, do you want your posts to be understood by everyone? or just a few?
Check out my other stories.
Stay connected, follow me
Thank you for using your precious time to read this article. Liked it? Clap your 👏 to say “thanks!” and please share it to help others find this article.
