Q. What is Not Clear, You Ask?

A. Nearly everything I respond.

In the last few years, I have found it more difficult to understand various aspects of IT in articles I read on an IT topic. This, you might say is age-related and therefore inevitable but, on reflection, I think there are other, significant factors involved in this brain fog.

1. Woolly titles which seems to be an amalgam of aspects of IT and do not attract the reader or shed much light of the content. Titles such as ROI of Microservices in the Hybrid Cloud give me indigestion and appear neither fish nor fowl, leaving me wondering what I might learn from the reading the article. They exude the message; Do Not Read: Boredom Ahead. Such stuff is tinkering around the great unexplained core IT knowledge, rather like telling you how to emulsion the walls of your house before you have learned how to build it.

2. Many articles are free of explanatory diagrams, particularly where they are meant to teach the reader about the topic; in the worst case, they are content-free as well. Some topics demand diagrams, for example, those on networks and networking topics cannot give a clear picture of what is going on without diagrams at some point. I no longer read network articles which have no diagrams.

Relying on words alone is often inadequate; sentences like The payload is vetted by the firewall before passing on to the router and thence to the intermediate server node, which is attached to the central server. After that the data goes to the backup server … convey little to the learner and I suspect even the expert might struggle with creating a mental image of the situation. An annotated image is easier for the brain to store and retrieve than blocks of text.

Figure 1: Unexplained Picture

Figure 2: Useless Picture

Not a grey hair in sight, ergo, no experience even if they were real IT people.

A total waste of your time, storage space and internet bandwidth to download it.

Nobody has ever explained to me the value of these pictures, mainly I suspect because they have none. Remember; He who wastes my time, steals my life ... and internet bandwidth.

3. By contrast, another enemy of understanding is the complex diagram inserted in the text and which is then left unexplained or only a very small part of it is. Hint: highlight the piece you are covering and leave the rest to serve as context. Anyone reading this article will recognise this dilemma and for those who don’t, some examples from real life are presented later. If you are not going to use a diagram or picture and explain it, don’t put it in or have it elsewhere and provide a link to it.

Hints on Marketing Clarity

As I said above, this article contains some suggestions for writers of IT articles and marketing datasheets. The format of the sample at the end of this article is, I feel, unique in that it consists of a spoof datasheet, based very closely on a real one which will demonstrate what I am trying to say without actually saying it. It is from the fictitious All Things to All Men software company (ATTAM).

The material was extracted from that article, which appeared a few years ago. I have modified it slightly to present as a how-not-to-present something to emphasise part of what I have said. I have not provided samples of the hooded man or the trendy, with-it IT people on the grounds that such pictures are useless and waste resources in being so. See item 2, above.

There was little in the way of explaining the purpose, business benefits, obstacles it can overcome and the sphere of IT the software fits in. I have seen similar presentations, often given to the wrong audience. None of the features and functions was explained; it was simply a "gee whiz, look at all this stuff we have" exercise.

What is the Way to Do It?

What I say here is not theory but lessons from my own and others’ experience with learning from books and articles and, latterly, videos and webinars where the conclusion of each brush with that learning mode ranged from "That was very informative" to "What was that all about?" Let me try to simply spell out what I think an article should do (and let me know where any of mine fall short).

Let me say upfront that the tight word and size limits often imposed by "publishers" on writers often make it impossible to do justice to some topics, where the writer’s options are to refuse to do it or emasculate the subject in "death by a thousand cuts." To the publisher who is really interested in the reader; offer to split the long articles into two or, if it is quite long, publish it as an eBook.

In this way, you will offer far more value to your readers and be the chosen destination for people who want quality, learned, satisfying articles.

The article submitted here as an example of a marketing article with a nonsensical picture for good measure. Note: It is not included as a criticism of Intel products or the company.

In contrast, look at (read if you wish) this article: A primer on DevOps pipeline: Continuous Integration & Continuous Delivery (CI/CD)

Download the full paper: A Plea for Clarity