Technical Writing in a Nutshell
A couple of things to get out of the way
Welcome to Decoded for Developers. We are excited to have you on board. We wanted to provide a few tips and recommendations on how to write awesome articles. We look forward to having you onboard as a writer!Writing is a skill. It’s taking your thoughts and organizing them into words in prose. Technical writing represents taking complex technical ideas and sharing them with simplicity and directness. If you’re getting started writing your first tutorial, don’t worry, we’re here to help out.
The first step to building out a tutorial is to have your sample app working. We recommend containerizing (check out Docker here) your application to prevent any issues with various development environments that developers would be developing in. I would also recommend laying out your thought process as you build your app within your comments or a README. This will help you map out the various sections of your article. With the outline set, you can begin fleshing out the content. This process often requires a shift from the analytical process that comes with programming and switch to a writing mentality. Finding your voice when writing is an important aspect of writing in general. It takes time and practice to develop but bears fruit in the long run. You can have a cheerful vibe or a general monotone (not fun but as long as it delivers the message). The core of it is, keep it short, sweet and simple. Code snippets are an essential part of the tutorial, so remember to use gist or code blocks to display the code that you want the reader to focus on or add into their code. Currently, we support links from Gist and HTML and Markdown syntax highlighting natively on the platform. (We will update this article once we have additional syntax highlighting for other languages)
Things to look out for
To polish up your article, there are a few pointers that might make your article stand out:
- As discussed above, find your voice in your writing
- Prepare before you write. Get the idea formulated in your mind, then start writing.
- Make sure your article remains fresh and relevant over time. Remember that this is going into a permanent repository of information. Readers from 2020 onward will be referring to your article for help. Avoid time dependent information on your article unless necessary. For example, explicit versions of software that may change over time (*clears throat, Angular). Every once in a while check your article, to make sure the info is as up to date as possible.
- Use references whenever you can. This helps the reader learn more about the topic from more fleshed out resources. This also helps you prevent scope creep. If you learned something from a company’s documentation, make sure to add it in as a resource.
- Use standard English when writing. This helps keep the article as readable as possible. It also helps anyone who wants to translate the article get a more accurate translation.
- Don’t worry about word-count. What matters is the content. Whether its 500 or 12000 words, as long as you are getting your point across.
- As I mentioned earlier in the article, remember writing is a skill. Its honed over time. By practicing, getting feedback from peers, mentors and our editorial team, you’ll keep on getting better. Stay hungry. Stay humble.
We’re happy to have you on this platform and if you’re passing by, share this with someone interested in taking on technical writing. It might save them a whole lot of hustle. See you on the other side :)