A Plea for Clarity in IT Writing
March 08, 2022

Terry Critchley
Author of "Making It in IT"

Share this

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

Dr. Terry Critchley is an IT consultant and author who previously worked for IBM, Oracle and Sun Microsystems
Share this

The Latest

December 01, 2022

You could argue that, until the pandemic, and the resulting shift to hybrid working, delivering flawless customer experiences and improving employee productivity were mutually exclusive activities. Evidence from Catchpoint's recently published Site Reliability Engineering (SRE) industry report suggests this is changing ...

November 30, 2022

There are many issues that can contribute to developer dissatisfaction on the job — inadequate pay and work-life imbalance, for example. But increasingly there's also a troubling and growing sense of lacking ownership and feeling out of control ... One key way to increase job satisfaction is to ameliorate this sense of ownership and control whenever possible, and approaches to observability offer several ways to do this ...

November 29, 2022

The need for real-time, reliable data is increasing, and that data is a necessity to remain competitive in today's business landscape. At the same time, observability has become even more critical with the complexity of a hybrid multi-cloud environment. To add to the challenges and complexity, the term "observability" has not been clearly defined ...

November 28, 2022

Many have assumed that the mainframe is a dying entity, but instead, a mainframe renaissance is underway. Despite this notion, we are ushering in a future of more strategic investments, increased capacity, and leading innovations ...

November 22, 2022

Most (85%) consumers shop online or via a mobile app, with 59% using these digital channels as their primary holiday shopping channel, according to the Black Friday Consumer Report from Perforce Software. As brands head into a highly profitable time of year, starting with Black Friday and Cyber Monday, it's imperative development teams prepare for peak traffic, optimal channel performance, and seamless user experiences to retain and attract shoppers ...

November 21, 2022

From staffing issues to ineffective cloud strategies, NetOps teams are looking at how to streamline processes, consolidate tools, and improve network monitoring. What are some best practices that can help achieve this? Let's dive into five ...

November 18, 2022

On November 1, Taylor Swift announced the Eras Tour ... the whole world is now standing in the same virtual queue, and even the most durable cloud architecture can't handle this level of deluge ...

November 17, 2022

OpenTelemetry, a collaborative open source observability project, has introduced a new network protocol that addresses the infrastructure management headache, coupled with collector configuration options to filter and reduce data volume ...

November 16, 2022

A unified view of digital infrastructure is essential for IT teams that must improve the digital user experience while boosting overall organizational productivity, according to a survey of IT managers in the United Arab Emirates (UAE), from Riverbed and market research firm IDC ...

November 15, 2022

Building the visibility infrastructure to make cloud networks observable is a complex technical challenge. But with careful planning and a few strategic decisions, it's possible to appropriately design, set up and manage visibility solutions for the cloud ...