On technical writing: is it easy or what

Technical writing is easy. Blogging is also easy.

It is just the research, idea mining and testing that are hard.

Recently I wrote an article on SSRS Administration on Simple-talk.com. Easy topic, right? What can be so complicated there – configuration of SSRS is easy, chosing a topology should be fairly straightforward, performance debugging should be easy…

Yes, these topics are pretty clear – and thousands of blogs, white papers and CAT articles exist on the subjects. Then what? Why should I write another one?

Here is how the process of technical writing goes (if you are already bored or if you are a technical writer – stop reading now and go make pancakes – if you are bored – I can’t help it, and in the latter case – you already know this).

 

The idea

Getting a good idea takes courage and time. Because it is quite pointless nowadays to write about something if someone has already written about it. The Search engines pick up on the fact and your rating does not go up much. On the other hand, if you want to be seen – you have to come up with unique content.

The reality is, that if something cannot be found online it does not mean that people are not looking for it.

It is time-consuming to find an idea which is demanded by more than a single person and has not been addressed before.

The bravery comes from the fact that if you pick a topic which is not popular and largely covered, then you have to dig into it and there is a big chance of failure due to discouragement, boredom or just being unable to conduct the research properly.

 

The research

Researching is another story: if you pick a topic which has been covered already, this puts you in a situation where you repeat like a parrot what others have said; if you pick a topic whic has not been covered anywhere, this puts you in a situation where you need to start digging, reading, testing functionality, contacting MVPs, CIOs, UFOs and other 3-letter entities. :) And this goes for days, or just as long as it takes.

After the research is done, I personally find myself with about 4000 words notepad document with notes, links, categorizations etc.

And this is the easy part. Wait untill the sorting of it!

 

The sorting

Sorting the research notes is probably the hardes part. The time spent on research can vary from a day to month, and there is no guarantee that a single detail which just took 1 week to research will make it in the final product. Usually the research is giving at least 50% more information that will end up in the final product.

And the more you have researched a topic, the harder it is to not write about it. True story.

 

The first draft

The first draft comes slowly and is usually directly linked to the idea, the research and the sorting, and it can easily throw you to “square one” if you have not done a good job beforehand. The first draft usually brings up thousand questions of the “what if” kind.

 

The second draft

Structurally and logically it has to sound good, otherwise there are plenty of smart people out there who will comment and you will have to answer. Also, there are plenty of silly/inexperienced people out there who take everything for granted and as the complete truth.

In either case, the way the information is presented matters.

 

The editing

Usually, no technical writer is good at editing their own works. Editing is a whole different story. And if the phases so far have not been done properly, the editor will most likely write a lot of questions or just take much of the article and format it as strikethrough. Not too much fun. :)

 

The third draft

Hopefully the final one. After the editor has returned the notes on the article, there is still some research and writing to be done. Usually a good introduction, a good finale are to be shaped here.

 

The publishing and promotion

There is no use of writing a good article if noone reads it. (hence, the zen question: “have you written a good article if noone has read it”)

 

Be open to comments

Any comments are an opportunity for improvement. People usually do not mean bad when they comment on technical articles. For example, look at Auke Teeninga’s article on Minesweeper in T-SQL. The article is smart, witty, pretty useless from the point of view of the average plebeian, but a lot of fun for the people who know what it takes to come up with and to actually write something like this.

Just look at the comments and you will see the vast variation.

All comments are good. The good news is that the insignificant ones can be ignored, the valid ones can be adressed, and noone ever means no evil.

 

The bottom line

At the end it all boils down to the following: this is a comment by a reader of the Minesweeper I mentioned earlier:

With that kind of skill you’d have a lot of free time or with the time it
took, you would have gained a lot of skill. Either way an employer wins
and as well do we. Thanks for the mind opening ability of T-SQL.

 

Make sure to check out my SSRS Performance Dashboard I wrote recently. I think it is useful.

 

 

 

 

 

1 comment to On technical writing: is it easy or what

  • I really loved this article. I go through this phase every day.

    I understand how much research we have to put in if the complex subject has to be put in simple words.

    Many thanks for writing this article it will be inspiration for all of us for long time.