A brief intro 🔗
When we think about technical writing such as documenting code, or writing articles, we can see some very obvious benefits, like:
- The code is easier to understand to others but also to you.
- You help others to learn.
- It can improve your CV.
- And you could even commercially profit from it.
Thats why in this post I will specially talk about some benefits that might not be that obvious at the beginning, but that actually makes you wanting to keep writing. Lets get started!
3 Benefits of technical writing 🔗
1 - Your knowledge and understanding drastically increase 🧠 🔗
Normally when I’m on a project and I get stuck, I would typically go to Google or check some documentation until I find an answer that works and then settle with that, does this sound familiar to you?
But when I write the process now change, and if you start to do it or if already you do, you may experience some of the following:
|What you may experience
|You start to think about the topics you feel you could write about, but at the same time you realize that there are topics you wouldn’t write cause you need to dig deeper into that topic.
|You become aware of your weak and strong areas of knowledge.
|Cause you want to avoid an overuse of expressions such as: “that line of code”, “that part”, or however your subconscious may call that, you might start to search more specific terms, like:“operator”, “conditional”, or other terms.
|You learn the correct terminology.
|You try to search good sources and documentation to corroborate what you are writing about.
|Look for reliable sources.
|As you read and write you start to remember things you learned in the past but also learn new and deeper stuff.
|You remember stuff.
|You start to ask yourself a lot of questions, like: “but what happens if […]?”, “is it correct to say that […]?”. Cause you want to make right statements, that might make you research more and even perform tests to probe what you are saying is truth.
|You research more and perform tests to prove you are right.
|Is not the same understanding something than knowing how to explain it to others, but as you research and try to explain it, things start to make even more sense.
|Abstract thoughts start to have more meaning as you explain them.
|Sometimes as you write about a topic you realize that there is so much to say about it that you might even split it and write another related article.
|You might realize there is a lot more to say than what you expected.
As you can notice, writing can make your learning deeper and of a better quality.
2 - It gives you confidence 🤹 🔗
Of course, cause now you know how to explain a subject to others, you will feel more comfortable talking about it, also cause you started to use the correct terminology, it starts to become more a natural part of your language, but not just that, as you code (if you do), or whatever you do, you’ll know better what’s going there and you might even feel tempted to research more in your trusted sources.
3 - Your grammar and language skills are increased 🖋 🔗
My native language is Spanish and I have certain understanding of English, but as I keep writing more and more in English I feel more confident with the language, and my grammar has improved and now I make fewer
Whether you are a native English speaker or not, or even if you decide to write in a different language, your grammar can be improved, and of course this could make you look even more professional.
7 Tips that can help you to write 🔗
1 - Make a list 📜 🔗
In that list put all the topics that you would like to write about whether or not you dominate that topic, this can force you to learn more about those topics when you decide to write about them. In my case I added a magnifying glass icon (🔍) to the topics I know I need to investigate further.
2 - Have on hand reliable sources 📑 🔗
These could be the places where you learned and know from experience that what is there has worked for you. If you’ll write about a software, framework or library this could be it’s own website documentation. Also you could rely on places that have good reputation, for example for me one could be MDN Web Docs, even though it might not be error-free I know that generally I can trust it.
3 - Perform tests 🧪 🔗
If you share code snippets or some kind of procedures, try to test them out to make sure that the output is as expected and what you are teaching is reliable as well.
4 - Use a spell checker 💡 🔗
If you are not typing in your native language or at Sonic speed (or both) is very likely that you’ll commit mistakes, in these cases having a spell checker is very handy.
In my case I write my articles in Markdown files and I installed an extension in VS Code called “Code Spell Checker“ which also distinguish CamelCase format and has worked pretty good for me.
5 - Credit your sources 💬 🔗
It doesn’t just give more credibility to your article, you can also help others directing some traffic to the sources where you already received some benefit, it can also help you to gain good reputation.
6 - Review it all again 🔬 🔗
This can help you to see where you need to make adjustments, if you repeated way too much an expression, see where you made grammatical errors, to check if it’s understandable as you read it, and also to know if you need to shorten some parts that are quite verbose or if you have to explain something a bit more.
7 - Publish it 📢 🔗
Before it goes public check that everything looks okay, check the preview of that article if possible. Also, if you’ll be able to receive comments they can provide valuable feedback. Finally what is left, is the satisfaction of accomplishment.
Final words 🔗
For sure, writing is time consuming and also requires hard work, but in the end can be very rewarding, I even think this could be a good step to become a senior developer.
Even though I only have some weeks of experience, I want to know how it will be when i have dozens of articles, so for sure I know that I want to keep writing, on the DEV Community, other websites, but also in this website.
Do I recommend it to you? Of course I do!
Credits: this article is based on self experience, but I recognize I obtained part of the experience in the DEV Community
This is a more recently (2023) modified article that I originally published at DEV: Link to the original post