Keys to Writing Technical Articles

If you are like me, if you see too much code, and things aren’t explained where it makes total sense, you stop reading. For me the article needs to:

  1. Be easy to follow
  2. Convince me that I should spend more time on this technical idea

Any tips to drawing people into reading technical articles?

Since your readers will come from various countries with different levels of understanding, then you need to write your articles in the most simple manner you can.

there is no technical data that cannot be more beautifully communicated than with well chosen charts, graphs, illustrations, and drawings – just ask tufte


Well, if we specifically talk about technical ‘writing’ only, we must give pointers and make them as manual guides or ‘How to’ articles.

only, we must give pointers and make them as manual guides or ‘How to’ articles.

We must, must we. What if how to fails to serve the reader’s interest?

One of the big problems people have when writing for the web, is failure to communicate the why to. This speaks to point two, in the OP, as being easier said than done.

Many sites submitted had no concern for the user on the most basic levels. Rarely could you identify an idea or purpose behind the site, or name a possible user goal the site was intended to facilitate. There was no flow, no legibility, no usability. It wasn’t so much that the designers had contempt for their users as that they seemed never to have been taught to think about users at all. One gets the feeling that the web design curriculum at too many colleges and universities consists of little more than tips on how to use Flash to imitate sites that won awards five years ago.

The Rebooter’s Children Go Rebootless, Jeffrey Zeldman

Let’s say you’re a web dev, and you want to attract clients. What many do, is publish an article about how to develop a site using the flavor of the week (CSS 3, HTML 5, Postgre, Jquery …whatever).

What does a client, in general, desire? Well the bare minimum competence of how to get things done, while important, doesn’t serve all the client’s needs.

Glacially slow on the uptake, web devs are getting the point if a client wants to know how to build a site without you …they are less than enthusiastic about hiring you. I call these “How Not To Hire Me” articles.

At best, you’re talking to prospects unwilling to be clients. At its more common worst, you’re getting traffic from other devs and designers, who will never hire you. Ever.

Who is going to pay rock bottom for a service? Someone who thinks they could just as well do it themseves. Yet that’s who most how to articles target.

Zeldman is a web dev guru, of sorts. His criticism carries the weight of someone who understands there’s a why to deficit.

The high-fives stopped. People adjusted themselves in their high-back leather chairs and the bank president stopped pacing and sat down. After a few minutes of discussion it became apparent that there was no objective or strategy in place. The project had no reason to exist except that the client wanted a website and the web designers sitting across from me liked money, so it seemed like a natural fit. Oops.

Never Get Involved in a Land War in Asia (or Build a Website for No Reason)

My suggestion is to never write plain, simple technical articles explaining how to do it yourself and never hire you. …Ever.

Stop writing plain clear how to articles about Zen Cart. Start writing articles about ecommerce that show clients how to double sales with three quick changes to any shopping cart. And why shopping cart developers could care less about sales, because all they support is the transaction at the end.

Stop writing articles about how to post an article in Wordpress. Start writing about how to use Worpress to accomplish actionable business goals. If the company needs education on the operation of a ten button text editor window UI, with tooltips, they’ve got much bigger problems.

Stop writing articles about how to install the latest technology. Start communicating your understanding about the reason why your clients should care.

Thanks for this much descriptive explanation and unveiling the secrets of real content writing.