1/ Split your articles into sections
Don't write everything in one section because it makes it difficult to read. Moreover, it also confuses the reader.
See the two pictures - which article is easier to read and less confusing?
2/ The layout is important
A proper layout makes an article easier and more enjoyable to read
Make use of:
- whitespace
- bullet points
- headings
- sub-headings
- images
Once again, compare the two articles without headings and bullet points.
3/ Write for clarity
Avoid using fancy words and terminology, if not needed.
If you can simplify your article, do so. Your job is not to sound smart, but to be as clear as possible.
4/ Split your text into paragraphs
Sometimes, I see articles that have 1 or 2 enormous paragraphs.
It's incredibly tiring and difficult to read such articles.
Compare the two images - isn't it harder to read the article with those walls of text?
5/ Code screenshots
Code screenshots are bad for accessibility. If you do not add alt text, you exclude visually impaired people.
Secondly, it's annoying for people who want to quickly try out a code snippet.
If you really want to use screenshots, try to add snippets as well.
6/ Short sentences and paragraphs
Split long sentences and walls of text into multiple:
- sentences
- paragraphs
Big walls of text put the readers off. It's tiring to read such articles!
Compare the two images and see which one is easier to digest!
That's it for now!
Any like/retweet/reply helps! ๐
Alternatively, you can subscribe to the technical writing newsletter
https://t.co/y8zA94c7Pr