This is part one of a series on writing a technical article. The advice might apply to non-technical articles, but I’m focusing specifically with my examples on technical pieces. Other parts are listed at the end of this article.
I deal with a lot of first time authors, people that are working in a technical field and want to publish some type of article to share their knowledge or work. And I see all sorts of quality of articles from highly polished and ready to release to drafts that aren't as good a quality as my ten year old might write.
Even allowing for the language differences from around the globe (I get submissions from many countries), the quality of writing is appalling at times, and even when it's not poorly written, it's often not well structured.
Pick a Theme
The first thing that I'd really suggest for people is to pick a topic, or theme, for your article. Think about what you want to write about and then write an abstract or at least a topic sentence.
As you write, you should be able to go back to your topic sentence or your theme at any point, at any paragraph, and you should be supporting that theme. You can diverge in your writing to make a point, or give an example, but your writing should almost always be supporting your theme. If it isn't, you're off track.
Focus, Focus, Focus
Too often I find technical writers worrying about losing people, worried about covering their bases, and so they try to spell out every detail, or they include lots of background about lightly related subjects, or they want to be sure that someone implementing this technique understands everything needed for the entire infrastructure.
Don't do that.
Focus on your small topic. If you are teaching someone about encrypting data in SQL Server or in an ASP.NET web page, don't tell us about configuring IIS or creating server certificates in SQL Server. If that's needed, mention it, but don't go into details. Point people to another article, or just the vendor documentation. Or Google if you must. But write about the one small piece of technology you have chosen and leave other parts for another article.
Write about what you are teaching us, and assume people have some base level of knowledge. That might be a beginner in a topic, or an advanced used, but no matter which level you write for, you can still focus on your one area.
One thing I usually tell people is that a good technical article tends to be in the 2-5 page range (perhaps longer if you have lots of images or code), but beyond that you might want to consider splitting it into two parts.
Tell Me, Show Me, Tell Me
Everything above is general advice for trying to determine what goes into the article, but how do you structure it? The "default" advice, the advice that I think everyone should follow until they're established and comfortable writing articles that someone else publishes, is this:
- tell me what you are going to write about
- show me what you told me
- tell me at the end what you told me
Or in other words, have an introduction, a detailed middle section, and then a conclusion. This is standard essay advice that most people get in grammar and high school, and it still applies for articles. Blogs can be different, but for an article, follow this advice.
The introduction should have your theme or topic sentence, and then some details that explain what you're showing, and perhaps some back story about how you discovered this, or how it fits into a common situation.
The details should be just that. Walk the user through your code, your settings, explaining things. You ought to be able to give the article to a non-technical, or low-technical user and they should be able to follow along. They might not understand, but they should be able to follow things.
I tend to advise people to show snippets of code and then explain them as they go rather then show a huge section of code at the beginning or end, but it can work either way. You can even make the code a download and reference sections or line numbers. If a technical person can't load code into an editor, they probably shouldn't be reading your article anyway.
For the conclusion, it feels silly, but summarize what you've said. Restating the theme does two things. One it reinforces things for the person reading. They'll agree that you've shown something and it will stick with them. Of course if you haven't done a good job, hopefully there's a feedback mechanism for you to find that out. The other thing is that in writing that conclusion, you should go back and think about what you've written up to that point. Does your conclusion really summarize things?
The conclusion for me also tends to include a teaser to another article, a way for the reader to move on, or perhaps a quick note about what (specifically) this technique has done for me.
Writing a Technical Article Series
The rest of the series on how to write a technical article.
- Part 1 – Structuring Your Article
- Part 2 – Finding Ideas
- Part 3 - Where to Publish
