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

May 26, 2022

Site reliability engineers are development-focused IT professionals who work on developing and implementing solutions that solve reliability, availability, and scale problems. On the other hand, DevOps engineers are ops-focused workers who solve development pipeline problems. While there is a divide between the two professions, both sets of engineers cross the gap regularly, delivering their expertise and opinions to the other side and vice versa ...

May 25, 2022

Site reliability engineering (SRE) is fast becoming an essential aspect of modern IT operations, particularly in highly scaled, big data environments. As businesses and industries shift to the digital and embrace new IT infrastructures and technologies to remain operational and competitive, the need for a new approach for IT teams to find and manage the balance between launching new systems and features and ensuring these are intuitive, reliable, and friendly for end users has intensified as well ...

May 24, 2022

The most sophisticated observability practitioners (leaders) are able to cut downtime costs by 90%, from an estimated $23.8 million annually to just $2.5 million, compared to observability beginners, according to the State of Observability 2022 from Splunk in collaboration with the Enterprise Strategy Group. What's more, leaders in observability are more innovative and more successful at achieving digital transformation outcomes and other initiatives ...

May 23, 2022

Programmatically tracked service level indicators (SLIs) are foundational to every site reliability engineering practice. When engineering teams have programmatic SLIs in place, they lessen the need to manually track performance and incident data. They're also able to reduce manual toil because our DevOps teams define the capabilities and metrics that define their SLI data, which they collect automatically — hence "programmatic" ...

May 19, 2022

Recently, a regional healthcare organization wanted to retire its legacy monitoring tools and adopt AIOps. The organization asked Windward Consulting to implement an AIOps strategy that would help streamline its outdated and unwieldy IT system management. Our team's AIOps implementation process helped this client and can help others in the industry too. Here's what my team did ...

May 18, 2022

You've likely heard it before: every business is a digital business. However, some businesses and sectors digitize more quickly than others. Healthcare has traditionally been on the slower side of digital transformation and technology adoption, but that's changing. As healthcare organizations roll out innovations at increasing velocity, they must build a long-term strategy for how they will maintain the uptime of their critical apps and services. And there's only one tool that can ensure this continuous availability in our modern IT ecosystems. AIOps can help IT Operations teams ensure the uptime of critical apps and services ...

May 17, 2022

Between 2012 to 2015 all of the hyperscalers attempted to use the legacy APM solutions to improve their own visibility. To no avail. The problem was that none of the previous generations of APM solutions could match the scaling demand, nor could they provide interoperability due to their proprietary and exclusive agentry ...

May 16, 2022

The DevOps journey begins by understanding a team's DevOps flow and identifying precisely what tasks deliver the best return on engineers' time when automated. The rest of this blog will help DevOps team managers by outlining what jobs can — and should be automated ...

May 12, 2022

A survey from Snow Software polled more than 500 IT leaders to determine the current state of cloud infrastructure. Nearly half of the IT leaders who responded agreed that cloud was critical to operations during the pandemic with the majority deploying a hybrid cloud strategy consisting of both public and private clouds. Unsurprisingly, over the last 12 months, the majority of respondents had increased overall cloud spend — a substantial increase over the 2020 findings ...

May 11, 2022

As we all know, the drastic changes in the world have caused the workforce to take a hybrid approach over the last two years. A lot of that time, being fully remote. With the back and forth between home and office, employees need ways to stay productive and access useful information necessary to complete their daily work. The ability to obtain a holistic view of data relevant to the user and get answers to topics, no matter the worker's location, is crucial for a successful and efficient hybrid working environment ...