My three tips for new technical writers
My advice on how to create the best technical tutorial you can!
Hello fellow nerds, how are you all doing? Today I’m happy to share with you my 3 tips for those looking to try their hand at technical writing. As someone who has been a technical writer for about a year and has reviewed others’ technical content, I can give you some advice that has helped me make the best content I can. If this is something that interests you, be sure to subscribe to my newsletter so you can be notified of when I publish a new blog post.
Why you should try technical writing
Before we start, it’s beneficial to begin by discussing why you should pursue technical writing. Of course, the most obvious reason is for you to show off your technical knowledge to a potential employer. Yet beyond that, something that people don’t realize is that teaching others can help you solidify your knowledge on that subject. By forcing yourself to organize your knowledge in a simplified, digestible way, you solidify that knowledge in your mind. By looking back at the details to share with others, you may notice gaps in your understanding. You may reach a point where you aren’t sure how to explain a concept to others in a simple way or even at all. I know for me this has happened and it not only made me learn new things, but it also allowed me to create a much better guide. Through this, I was able to include things that the sources I’ve used glossed over or skipped altogether.
Another thing to consider is the confidence-building aspect of publishing content. By putting out your work to the public eye and doing so often, you are building some confidence in both yourself and your abilities. If you want to build confidence in yourself in general or in a specific field, you need to be able to put yourself out there and face the potential for criticism and rejection. While this may seem like something besides the point in all this, confidence is a very strong indicator of and catalyst for future success. I know for sure that a lack of confidence and fear of criticism has held me back in life and so starting this blog is a part of my process in overcoming that.
With that out of the way, you should now understand why technical writing is worth pursuing. You not only teach others but you teach yourself and help create a personal brand. That’s not even including the satisfaction of helping other people!
Tip 1: Don’t be afraid to cover something you aren’t an expert in
To start, I’d say that contrary to what you might think, you don’t need to be some expert to write about a specific topic. Of course, that’s not to say that you shouldn’t have some competency or know what you are doing but you can get away with teaching what you’ve just learned. In fact, I’d even say that that can be a huge advantage! I find that if I’m teaching something I’ve learned a long time ago, it becomes very easy to gloss over things and not understand your audience since you are way ahead of them and thus less relatable. Meanwhile, if I just learned the topic that I’m teaching, I can understand my audience better because I was just there and so I know what would be confusing for a beginner. This way, you can create a guide even better than what someone more seasoned than you could do because you know your audience and can be more down to earth with them
Tip 2: Be down to earth and pragmatic
If you are reading a technical tutorial, you want something that’s not overly complicated to read and goes straight to the point. I find a lot of the time when I’m researching a technology/library I like to briefly skim through articles to quickly find what I’m looking for in plain English. Don’t try to sound fancy and use overly complex phrasing because, in the end, people are reading it to find the results they want. Keeping it simple yet sweet is far more appealing because the complexity will just make it harder for people to get the results they are looking for. That’s not to say that you shouldn’t add a lot of detail to your work it’s just that you should keep it as concise as possible. Although I tend to write content on the longer side, I do so because I try to add a lot of detail that just can’t be condensed down.
As a related side note, since people often skim guides for particular answers, you should consider putting a table of contents for them to easily find what they want.
One specific example of people doing this wrong is with passive voice (which I’ll admit I have been very guilty of before). Passive voice refers to when you have a sentence with a noun performing an action but you phrase it so that the action comes before the noun. So for instance: the cake was eaten by John (passive voice) versus John ate the cake. While it’s okay to do this sometimes I find that it can make things sound overly complex. Even worse is that sometimes when we use the passive voice we tend to omit what the noun is altogether and just say something like the cake was eaten. While that might seem small, I try to avoid doing that to make the concept clear as glass so readers don’t have any holes in their knowledge.
Tip 3: Be visual when possible
As an extension of the previous tip, being visual can further help make the point clear to your audience. I remember earlier on when I was learning to code, the online content creators that I got the most out of and influence the way I teach were very down-to-earth and visual. A big part of this was that they were teaching via YouTube videos.
Side note: if you are curious about who these YouTubers are they are TheNewBoston and Telusko
Not only that but they would use visual elements like pictures and diagrams which made the experience more engaging and fun. I found that this more engaging style made the concepts stick right in my head. One really good example of this is a video I found on the basics of recursion. In this video, the teacher clearly shows how recursion works by showing clones of himself talking to each other as function calls. While I already understood recursion at the time I thought this explanation was masterful and is definitely worth seeing.
Conversely, I find learning to code from books very daunting sometimes because of how many of them are less on the visual side. One book that has helped me however was head-first java which, as you could guess by now, masterfully uses visuals. Just look at this amazing visual analogy they used:
If that won't drill the concept of serialization and deserialization in your head I don't know what will!
While it’s true that not everyone is a purely visual learner, the human mind to me seems to work a lot better with images. This isn’t purely limited to actual pictures, however. When I say to be visual, it can also mean to use clear analogies. I find that a good analogy can be the deciding factor sometimes in how deeply I understand a concept.
How I normally structure my writing
To close this guide, I thought I'd share how I normally like to structure my content. Of course, you should have your own style and do what works best for you, but this is just the style that I've found most effective for me:
Start with a brief introduction summarizing what the guide will go through and why the reader should be interested.
Layout the prerequisites for the reader to properly follow the guide, if any.
Give the reader the general theory around the technology/library you are showing them. Do so as clearly and simply as possible for them to understand. This section is likely where visual aids would most be in use.
Walk step by step over a full implementation of what you just explained to them using actual code.
Give a conclusion summarizing what you've done and explain what the reader can do to further their understanding.
This formula is based on what I've seen in the guides that have best helped me and my own personal preferences. One of my guides that I'm most proud of clearly demonstrates this style of writing if you want to see it in action.
Conclusion
With that, you should have an understanding of the strategies I recommend for technical writing or tutorials in general. Of course, for technical writing, all this won't matter as much if you don't have good spelling and grammar so brush up there too if you need to. Hopefully, this will help you write some awesome tutorials in the future or convince you to give technical writing a shot.
If you like what you read, consider subscribing to my newsletter to be notified of new blog posts. Also, check out my programming tutorials here.