Basic tips for technical writing

February 1, 2019

Technical writing is any form of writing that helps break down technical tools, practices, opinions and ideas. It has rapidly become a valuable skill at all levels for anyone in a tech related career, developers and even designers.

I strongly believe everyone regardless of their skill level should embrace the opportunity of writing about what they are learning, opinions and even ideas they might find difficult to implement. It’s a great way to not only grow an audience and a network, but also a platform to put yourself out there and showcase your knowledge.

As you venture into technical writing however, regardless of the complexity of your writing, here are a couple things you should keep in mind and attempt to get used to as much as possible.

Capitalizing brand names

Brands, just as the name implies have a specific way they are to be represented. When making any reference to any product, project or even library that has branded itself in a specific way, it is good practice to name these brands accordingly. Mentioning angularjs, react, twitter, github, nextjs, etc can also get lost in context for some readers. However, naming correctly like AngularJs, React, Twitter, GitHub, NextJS etc have the mentions of these products standing out and readers can easily identify them.

Syntax highlighting and formatting on code

Code can really get complex or even long at times. Nothing makes it easier for readers than having your code appear like it would when they have it in their editors. It immediately addresses the eye test of whether they are doing it right and at the same time, makes the entire article more comprehensible. Some blogging platforms come with great syntax highlighting for code, but you can also use GitHub Gists when needed or for longer blocks of code.

Use correct punctuation as much as possible.

This also applies to pretty much any kind of writing. A sentence with wrong punctuations can make it harder to read and understand or even worse, misinterpreted. Colons (:) can be used just before showing a block of code, avoid using periods (.) after exclamations(!) or question marks(?). Not all readers will have English as their first language so it pays to make your writing as clear as possible.

Keep an end goal, what do you want the audience to achieve at the end of the article

Having an end goal in mind keeps you focused on the article. Helps you wean out unnecessary information and keeps the article as specific as possible. As you start out writing an article, identify what you want the readers to take away from the article. Is it better understanding of a new tool, process, or you want them to learn new ways to do a specific thing.

Review your code like a prospective reader before publishing.

I strongly believe this is the best way to confirm that the code you have put up in the tutorial is working as it should. While writing, it’s easy to omit a line or skip a step or vital function and everything breaks with the reader having no clue how to proceed. Once you believe your article is done, create a new folder and go through the article from the beginning flowing each step to ensure that any reader can do the same.

Conclusion

As mentioned above, I think everyone can get into technical writing to share what they learn or trying to learn with other people. And like coding in itself, you can only continue to get better at it with practice. I hope these basic tips help you take your technical writing in general to the next level.


comments powered by Disqus