Technical Writing: Setup
A Sample Setup for Writing Technical Articles
Introduction¶
The advantage of writing technical articles is not only the chance to share your knowledge with others but in particular, it deepens your understanding of a certain topic since you cannot explain what you haven't understood. In this short article, I want to share my technical setup with you and introduce you to the fairly simple review process I established for myself.
Markdown Editor¶
Let's start with the number one tool: The editor. I like to write my articles in markdown. As many publishing platforms these days support writing articles in markdown as well, it is just natural to write your articles in it. The syntax is not only easy but less distracting than LaTeX. Furthermore, it is easier to integrate into publishing processes than Microsoft Word documents.
I use Typora to write my articles. It is a free markdown editor, which is available for all major operating systems. What I like most about it is its simplicity. Markdown code is directly rendered, so you do not have a split-view like in Visual Studio Code (VS Code).
Recently, I discovered Mark Text, which seems a nice alternative to Typora. The major advantage that I see is that it is open-source, so it is easier to write custom extensions if needed. Yet, the keybindings are not as natural as the ones from Typora and it seems like I need to spend some more time getting my hands on it. For the moment, I go with Typora.
Ide¶
When I write technical articles, source code is usually included, too. The source code is not only tested but also shared via GitHub. Typically, I use VS Code to create the supporting material for my articles.
VS Code is much more light-weight than PyCharm. I use PyCharm mainly for big Python projects as it is better in that regard (at least in my humble opinion). However, the supporting material for my articles is mostly pretty small. Therefore, a heavy-weight IDE is not necessary.
Bonus: All functionalities provided by VS Code are free - for everyone. Furthermore, its set of third-party extensions is growing rapidly. In my opinion, it is worth checking out.
Review Process¶
To ensure a quality that satisfies my aspirations, I established a review process, which consists of four steps.
- I re-read the whole article and make sure that the statements I wanted to make are as clear as I want them. I do not do this immediately after finishing the article. Rather, I wait for a couple of hours or even days before re-reading it. This way, I can establish a certain distance between me and my work, which allows me to be more critical with it.
- The second step involves sending the article to Grammarly. Grammarly is a service, which checks the spelling of your texts and gives you advice concerning your grammar. Furthermore, it tells you how your text sounds and even suggests you different words or phrases based on your audience. There is even an unofficial VS Code extension for Grammarly worth checking out!
- In the next step, I proofread my article again. This time, I do not focus on the content but the language. Even though Grammarly does a great job when it comes to detecting spelling and grammar mistakes, it performs poorly on suggesting real alternatives and synonyms, which would make the article more readable.
- In the last step, I send the article to a second person for proofreading. For the review process, we use GitHub. This way, it is easier to make suggestions, track changes, and discuss certain parts of the article. Make sure to send it to someone, who represents your audience best and who is willing to learn something new or knows your topic.
Summary¶
And that's it! If you have any questions concerning the tools described in this article or the review process, do not hesitate to contact me. Furthermore, if you would like to be an author but do not know where to start, feel free to contact me, too!
I hope you enjoyed reading this article. Make sure to share it with your friends and colleagues. If you have feedback, let me know - I am eager to hear it! Also, make sure to follow me on Twitter, where I am @DahlitzF.