How to Write a Technical Blog That Gets Read

There is a relatively simple and quickly learned technique to writing a blog that people will want to read. We asked an anonymous successful blogger, who is widely read, how it is done. I will try to explain, purely from my experience (and the editors before me), how to write articles, blogs, features, or short pieces people will want to read.

Choosing Your Subject

Coming up with a topic is typically the most challenging task, probably not for the reasons you think. Everyone has topics in their life that they could write about if they wanted to. Thousands of things, actually. Everything you do every day could be a blog. In fact, think of any task you have completed this week and go to your search engine. You will find instructional blogs, videos, books, and everything.

Warning, I actually do mean anything, and I am not liable for what you search for on your company computer.

Now, limit your ideas to technical topics, and you have topics to write about. What is hard is matching the topic to the size you want your written piece to be. If you want to write about being a cross-platform DBA, you need an entire book to go into detail. And when you write that book, the first thing they will make you do is break down those topics into chapters and then sections.

General advice. Pick the topic you are interested in and outline it. Think about what you want to say. It may be too small of an idea, which does happen every 10 years or so. Usually, you will find that you have uncovered a series of blogs to write.

The opening

Writing is like having a one-way conversation. Just as when you engage in conversation, you have to be aware of what the other participant wants: In the case of an article, the reader will probably first want to know in advance if it will be worth reading.

It is best to start by briefly explaining what you want to say and why the reader should continue reading. The reader will give you a narrow window of attention: Take it. Starting with a title and going right into the first paragraph, you want to be clear about what problem you will help them solve or what advice you are giving. If that isn’t what they are looking for, they probably aren’t going to read on. If they liked what they read in the first paragraph, they may pick your article first the next time. 

Because of this, the first paragraph you write is by far the most important.

You don’t have to give away everything in that first paragraph, but this is also not a murder-mystery novel where you are trying to intrigue all readers into reading about a topic. No matter how well-written the article, the reader probably isn’t going to continue reading an article on “database server tips” if they were looking for details on how much to tip their server. Not even if you start out your blog, “It was a dark and stormy night.”

In fact, you will find that most people come to your blog from a search engine, looking for a specific solution or advice. The opening paragraph needs to let them know what they are getting and whether to keep going.

Writing the Rest of the Article

After you set the tone with an opening, the rest of the process is relatively straightforward. In this section, I will give some basic advice. First, choosing a style for your article, and then give some general writing mechanics advice.

Style

There are two styles of writing a technical article that works excellently. They are not mutually exclusive; best case, you will get some of both. The two styles are telling stories and demonstrating concepts.

Storytelling is taking some occurrence you have experienced and telling the story. Someone had a breach, and here is why. On a project, we had to uppercase all the documents in a system. I had to work all night last night fixing a problem you may be up against someday. A DBA and developer walk into a bar… Stories don’t have to be completely real, but usually, realistic helps.

Telling a story helps the reader relate to what you are writing about, so it draws them in.

The other way is to demonstrate a concept, like an article on using a new language concept. Say there is a new function named UpperCase in a language you want to highlight. Walking through the generic uses of this new function can be a great article. Here is what it does, what it doesn’t do, and how it performs. The more authentic your explanation is, the better, but it doesn’t have to be connected to any reality.

In the best case, you can tie the two together. “A few years ago, we were working on this project, and we needed to capitalize all the words in a document. At the time, there was no built-in way to do this, so we had to do…Now, you can do this, and let me show you all the things you can do.” Adding a bit of story to a demo can draw people in because they realize that what is being done sounds like something they might have to do one day.

Note that when you tell a story, be careful not to just drop the story element altogether as the blog progresses. The story adds a theme to your blog that people will want closure on if they read it in detail. Did you actually get those documents upper cased? Or did you fail? Either way, you will probably connect with readers as we all have succeeded and failed many times.

Mechanics

In this section, I will cover some general advice for writing. These pieces of advice are specially tailored to writing a technical article for public consumption. All rules are meant to be broken occasionally, but this advice will go a long way.

Keep things generally professional. If you want to attract a wide readership, it is generally best to not lapse into dialect, swearing, or deliberately setting out to be disgusting. When you’re chatting with your peer group, these may seem a suitable bonding techniques. Still, on a blog or in an article, it invariably looks ridiculous. You should, by contrast, go out of your way to write clearly and inoffensively.

Moderate the use of jargon\acronyms. Be careful to not speak with the unique argot of any closed group that may be readers. Narrowly used business or technical jargon seems fine when used at work, but when written down and read by people from widely different cultures, it can seem bizarre. Ideally, speak to the people with the lowest understanding of your source material.

If jargon is bad, acronyms can confuse people badly, even if they are experts in the field but just haven’t seen the acronym before. So always define acronyms.

As an example, if you are writing about database query optimization, speak to people who write queries already and want to make them go faster. You don’t have to explain what a query is or how to connect to a server, but you might need to explain the different join algorithms and how to access information on what the query is doing. At least give readers links you find valuable to do that. People who know what a hash match join is won’t mind a bit of reminding. Readers that are clueless to what that is may give up after hitting the one-star review button and keep scanning for search results on a different site next time.

Don’t try to sound like a word-a-day calendar. In the previous paragraph was the word argot. This was written by the writer of the first version of this document, and I had to look it up. It basically means jargon.

Don’t dumb things down too much, and using a not-super-common word occasionally is not a big problem (and can be a good tactic to get the reader interested. Just don’t try to make yourself sound like an English professor.

Generally, avoid emojis/emojis. It will seem incredible to many that emoticons are not part of international English: they are a prop to casual written discussion, but any prose must be of sufficient quality to convey the emotion you require.

Show your work or show your sources. If you present information as fact, you need to give a supporting reference or prove that it is fact. For example, if you say that the UpperCase function makes all the characters of a string uppercase, link to it in the documentation or provide examples of it working. Ideally both. It isn’t weak to give readers more information.

One of the more annoying things to read in an article is boasts of the casualness of your writing, like ‘I haven’t the time to explain …blah …’ is a big turn-off. Why should they put in the effort to read it? Note that this is different from saying ‘I don’t know.’ You aren’t writing the documentation for a product, you are sharing some information about it. You may still have questions you would like to know. It is okay to say that.

Be clear in your writing but never dull. Never be afraid of striking up an attitude or showing emotion but do it with subtlety. Be conservative with your material. You need as few ideas or messages as possible, but they must be as good as you can possibly make them. Never confuse quantity and quality. Although metaphor, simile, and adjective need to be appropriate, never be too clichéd.

A final rule in writing a compelling article is to occasionally break a rule. The best articles show a certain tension and risk as if watching a high-wire act. Will the writer somehow drop off?

For example, note the advice to not use uncommon words. Sometimes, you need to prod the reader into full wakefulness with an unusual word, phrase, or saying.

Finishing up

To wrap up an article, the final paragraphs should enable the article, like an airplane, to land gracefully. It helps to recap the main points you’ve made and maybe plant an idea that leads the reader to learn more about your topic.

Summarize the points you have made to remind the reader what you have said, but it doesn’t need to be a checklist of everything you have said.

—————

If you have tips or concepts, add them to the comments for the post and I will update this article to reflect them.

 

The post How to Write a Technical Blog That Gets Read appeared first on Simple Talk.

from Simple Talk https://ift.tt/cnj2JGS
via