Technical writing is an important component of a software developer's job profile. Although blogs are a casual form of technical writing, they are not only just a way to give back to the community, they can prove to be a source of professional opportunities.
Therefore, it is important to make our writing as professional as possible whether we are doing it for the community or for our future.
Here's my advice to people who are willing to take a step towards improving their technical writing skills.
Use simple terms
Do not expect the audience to be familiar with complex technical terms. Make the language as easy to understand as possible.
At the same time, avoid slangs. It is not very inclusive to write in a particular dialect. Use simple English which everybody can read and connect with. Its fine to use a different language if your purpose is to make learning easier for your geographical community.
Structured into small sections
- Divide the article into sections,
- Use good formatting,
- Highlight the keywords,
- use bullet points where necessary,
- make use of code blocks to write code,
- Use images/screen-captures to convey the message if necessary
Nobody likes to read long paragraphs - keep them short.
SEO
Are your blogs searchable? If they get popular, will they show up in a Google search?
Out of my total post views, ~20% have come from Google search and another ~22% have come from Google temporarily suggesting the articles to Android and Chrome users.
Keep the title, keywords and content of your blog aligned to this requirement. Words like "how to", "create" and "learn" go a long way in getting your article a good page rank. Keep the name similar to what you would put in a search box.
Don't explain side topics
Don't explain things which can be explained well with external references. Add documentation links, course/video references and refer to other articles wherever necessary. Focus on the core of your topic.
Who should read it and why?
Explain who the topic is relevant for and why they should read it. Everybody has a limited amount of time. They will spend time on your article only if they think it would be relevant to them.
Create that relevance at the beginning of your article. The first few seconds of reading your content should be enough for anyone to make that decision.
Proof reading
Proof read your article for grammatical mistakes and typos. At the same time, read it from a reader's perspective and judge its simplicity and language. Optimise wherever needed. Be careful to not aim for perfection. Getting it out there is equally important.
Another strategy is to have a peer who reviews your article or a student who can give direct feedback. This can be done even after publishing.
A simple title
Do not make the title too complex by including all the technologies you are about to talk about. Title is all people will see before clicking on the post.
Make it interesting enough to be clicked (not a complete clickbait) and at the same time keep it true to its content. A cover image can be an added advantage.
Future improvements
Don't forget to revisit and update them if you find improvements in the future.
There will be situations where you will find a need to update your blog.
- to correct mistakes
- to accommodate software updates
- working on a feedback
Consistency and ideas
You need to write often to improve at it and to create a following of readers. Coming up with ideas to write about can be hard in itself. The easiest part is to write about things you are learning.
There are many more ways to come up with article ideas. Check-out the below article by Chris Bongers to explore some ways:
Learn how to come up with article ideas and stay consistent
Another place to look for is the Request for Article section.
Thanks for reading! I hope the post was useful in providing you with some guidelines for your blog posts. If you have something to add or debate on, feel free to drop a comment.
If you like my ideas, make sure you connect with me on Twitter to catch all my thoughts and progress.
