James Gallagher

good technical writing

Published on June 9, 2020 in writing

I stumbled into technical writing seemingly by accident. One day, my boss told me that there was a JavaScript article that he wanted written for our publication. I decided to take it on because I have been using JavaScript for years. I saw it as a fun assignment: an article unlike any other that I had written. Never did I expect that one article would redefine what I am doing today.

Technical writing is unlike any other writing that I have done before. Prior to starting my technical writing work, I never thought there would be an excuse for me to have both a code editor and a writing terminal open at the same time. It turns out that this is actually a wonderful hybrid. Writing about technology and programming is really interesting. Not only do you have to figure out what to write, but you have to develop the code that supports what you are writing.

Technical writing can be broken down into a number of tasks, like any type of writing -- from research and discovery to validation and writing -- but there are two main parts that I want to focus on: writing and developing good code to support your work. Of course, the topics you choose to write about will have a massive impact on the quality of your writing. If you're no good at Linux, don't try to write an explainer article on how to use a Linux command. Your expertise in programming really does show when you're writing technical articles. There's no way to mask your inexperience.

To write a good technical article, the first thing you should do is to think of your writing as only one piece of the puzzle. It's tempting to get really caught up in every word you write, trying to ensure that everything makes sense as you write. This may work when you're writing a regular article, but for technical writing it's a different story. You can't just write a technical article off the top of your head. You need to work on both coding and writing at the same time.

In an article I was writing this morning, I found myself focusing too much on the content direction that I wanted to take in the article. Then, about half-way through, I realized that the programming examples I was constructing did not support the extended topics I wanted to cover. If I had focused a bit more on the engineering to start, this wouldn't have happened. But because I let my mind go astray and focus on content first, I lost sight of all of the main technical points that I wanted to cover.

Before you begin writing a technical article, you need to consider what it is that you want to include, and what it is that you're going to skip over. Knowing what to include will help you ensure that you write all the code you need to write a good article. Equally important is knowing what not to include: technical articles can get really verbose if you don't get to the point. If someone is looking for a tutorial on how to center text using CSS, they don't want a five-thousand word essay about what each attribute you have used in your examples mean. They want a simple explainer to help them get through the problems that they're facing.

You may be asking: what should I include? How do I know if I am covering the right topics? The truth is that you're probably going to miss something, but that's okay. There will likely be other resources out there to which someone can refer if your article doesn't cover their exact needs. Because programming is so versatile, it's very unlikely that you will be able to write a definitive guide to anything. Even if you do, it's likely that it will go out of date at some point, or lose relevance as a new technique emerges that provides a more efficient solution to the problem you are trying to solve.

The best way to figure out what to include is to ask yourself two questions. These are:

  • What would I want to read if I was facing this problem?
  • What would the target reader for this article want to read?

Let's say you are writing an article as an introduction to the command line. I know that I would want to read about the top command line commands, what the command line was used for, and maybe learn a bit about the background of how command lines differ between Unix-based systems and Windows. It would also be great to read a primer on how I can open a command line. I would be willing to bet that anyone who is looking to read an intro to the command line would want these things.

Granted, some readers may want to know how to set up a Unix-based command line on Windows. Some people may want a deep-dive into grep. That's fine: everyone has different needs. Although I wouldn't cover all of these things in one article, because if I did my work would be too long. It's important that you always stay focused on the problem the developer who is reading your article wants to solve. If you're going off on tangents everywhere in the article, then the developer will get confused.

Similarly, don't explain everything that you discuss. Although many writers say that you should never assume, there are times when you will have to. You don't want to spend half your article telling a user how to install a package that they will need to solve one simple problem. If you think the user may struggle to get set up, point them to another article that could help. Better yet, write one yourself and link to it, so that the reader can choose whether or not they want to read about configuration.

I also believe it's important to be upfront about requirements in your tutorials. Does the reader need to be using a Unix-based shell environment to follow along with your writing? Do they need to be using a specific version of Python? Don't bury this information until later in your article. The reader needs to know it as soon as possible so that they can decide whether the tutorial's for them. Consider this: would you want to start following along with a tutorial only to realize it uses a different tech stack than you? How would that make you feel?

This section is best left until you have finished writing an article. What I have found is that, when I set out to write an article, I can sometimes discover new tools and libraries that will allow me to improve my technical work. If I were to write about requirements too early, then there is a high chance that those would become obsolete by the end of the article. Always be sure your requirements are comprehensive.

In writing this article, I have found myself referring to the "reader" as a "user." This was accidental, but it may be the best piece of advice I have for you about how to write good technical articles. The reader is not just someone who is passively reading your article with a cup of tea in one hand and their mouse on the other (although they may be for a few seconds, they likely won't be sitting like that for long!). Most of the people who read my work are looking for clear solutions to technical problems, or explanations of programming concepts. As a result, I can't think of them as just people who want to read my work. It's likely they are going to be following along actively with a coding terminal on one side of their screen.

This mindset has a couple of implications on how you should write technical articles.

First, you should ensure that you provide a good user experience. What does this mean? You're talking about technical writing, right? Don't leave this article just yet and decry me as someone who doesn't know what they are talking about. Hear me out. A good user experience means that you provide the developer everything they need to solve the problem they are facing.

This takes a couple of forms. For me, I like to include code snippets as often as possible in my articles. Sometimes, I even include multiple code snippets with the same modules or functions that I am explaining. The reason I do this is because I know that some people need multiple examples to help them work through a problem; providing two examples helps me better serve the user. In addition, you may also want to provide a GitHub repo with demo code that the user can work with alongside your tutorial. I am still experimenting with this medium, but I think it could be beneficial.

A good user experience also means that you don't try to do too many things at once. I've done this a few times in my career, and it has resulted in my rewriting a few pieces from when I started my technical writing. It's easy to think of three different solutions to a problem and talk about them all in one article, or to go through four different examples just to make sure the user gets what you are saying. There are situations where this kind of writing is prudent -- especially when you're discussing a really difficult topic that requires you taking it slow and walking through many examples -- but either way you should always retain a clear focus on what problem you want your article to solve. Don't try to be a generic "magic potion" that solves every need a developer has; you want to be the "love potion" that helps them solve the exact problem they are facing.

Second, you should think of your technical articles not just as a piece of writing, but as a product. This means that while the words you write matter, so does whether or not those words actually flow well with the technical side of your article. Do your code snippets make sense? Do your descriptions accurately describe what is going on? And, importantly: does your article adequately solve the problem for which you are writing a solution? If you are writing a tutorial on how to read files using Python's csv module and you don't talk about how to open files, it's possible that a user may be confused. You may have technically provided a solution by giving an example of reading files, but if you don't explain how to open them -- a necessary step before you go on to read a file -- then where do you think the user will be?

That said, the words in your article are important. No good technical article I have ever read has come with an excellent codebase and snippets but without any good descriptions. As a result, the standard writing advice applies, which I'm not going to delve into because every writer has their own style. You can pretty much guess the kinds of things that I would say anyway: double-check your work, ensure it makes sense, remove verbose language, et cetera et cetera. You get the picture.

Technical writing is a craft, and so I am still trying to get better at it. I think I have many other insights in my mind to share about technical writing that I just haven't unearthed yet because I am practicing and exploring new techniques so often. What I would say is that technical writing, done well, can have a major impact on someone's life. Think about it this way: how do you feel when you solve a bug, or build a new feature? That's the kind of experience you can instill in someone with good technical writing. I'm not exactly sure how many people my articles have helped -- page views are not exactly indicative of value -- but I do know one thing: I've probably helped at least one person solve a really tough bug. I know how frustrating it can be to encounter a tough bug, so knowing that I've been able to do that for at least one person is all that I need to hear.

For accountability: I plan to write another version of this article when my thoughts have crystallized a bit more. Until then, consider this my incomplete thoughts on how to write good technical articles.

Webmentions (0)

There are no webmentions on this post.
Your webmention must begin with http[s]://
Do you have any feedback on this blog post? Send me an email.
Do you want to hear more from me? Subscribe to my weekly Coffee with James newsletter.
Made by @jamesg_oca. Code on GitHub.
←  An IndieWeb Webring πŸ•ΈπŸ’ Β β†’