This post is yet another rant about the quality of the technical writing I have been seeing lately. In a LinkedIn discussion-forum about technical writing, I came across a link to a blog post wherein the author seems to both embrace and exemplify the aesthetic called "wabi-sabi" (a Japanese term that generally means embracing imperfections for their artistic value) for technical writing. Personally, I see that as nothing but an excuse for bad writing. As LinkedIn does not have room in their comment field for a rant of this length, I have posted it here.
Perfection in anything is impossible. However, I believe the Wabi-Sabi aesthetic has no place in technical writing. Wabi-sabi embraces imperfections almost to the point of idolizing them. Wabi-sabi began as a mindset of appreciating the imperfections that come with age and wear but has become an aesthetic of intentionally introducing flaws for artistic effect. While technical writing is "an art" it is not Art (with a capital 'A'). For far too many technical writers - or at least people who like to call themselves technical writers - this wabi-sabi aesthetic seems to have become nothing but an excuse for bad writing.
This article (and the author's entire blog) is a perfect example. There are so many errors it is almost unreadable. It strikes me as nothing more than "content" generated by the vast internet-content grist mills. I understand that this author is very likely not a native English speaker. However, he has chosen to write in English and to write - of all things - about writing. Therefore, it is reasonable to expect said author to actually learn to use the words, idioms, and grammar of said chosen language. He hasn't even come close.
I know it has become the social norm to never say anything negative about anyone. I know it is politically correct to never criticize the English skills of non-native English speakers and writers. While these touchy-feely notions may help everyone to "just get along," (or at least feel as if they are) those norms are destroying the craft of technical writing. We owe it to our craft and to our fellow craftspeople to call out this abysmal "content generation" for what it is. To not do so is a disservice both to the author and to all the readers of all the "content" they will ever produce. I am not saying we must pin on our "Grammar Police" badges and march into every internet forum, derailing the conversation and starting flame wars. However, just because some trolls used grammar critique as the lamest form of ad-hominem attack, way back in the early days of the internet, it does not mean all grammar critique is an attack nor is the critiquer necessarily a troll. When the topic of discussion is writing or when the author claims to be a professional writer, then it is perfectly reasonable to hold said writing to a higher standard.
With all that said, I will refrain from offering specific criticisms of the linked-to article. There are simply far too many errors to even begin to list them all. Almost every sentence is constructed poorly. Almost every idiom is used improperly. The numerous examples of incorrect word usage makes me wonder if the author has ever picked up a dictionary in his life. The introduction has almost nothing to do with the topic at hand and is also vaguely misogynistic, with only a clumsy transition from the introduction to the actual topic. What boggles my mind is that this person claims to actually work as a technical writer. What boggles said mind still further is that so many companies seem content to employ such abysmal writers and publish their "content" for the rest of the world to see.
As a former network manager, budding software developer, student of informatics, and all-around technology nerd, I have read a lot of technical documentation. I have watched for forty years as the craft has steadily gone down hill. From how-to books and articles in Popular Electronics which fully explained every detail in a way that even a thirteen-year-old could understand, to Byte Magazine articles which seemed intent on introducing a new acronym in each paragraph, to the infamous "help" files in software, to 1000-page books that merely repeated the "help" files with a lot of pictures to fill in the space, to software and equipment with manuals so terse they tell one nothing, to entire books devoted to telling the reader how great it will be when the author finally gets to the point (which they never do), and now to blog posts embracing and exemplifying wabi-sabi as a desired "aesthetic" in technical writing. Seriously? What's next? Embracing the randomness of writing words on 3x5 cards and spraying them about the room as an existential exercise in experiencing the essence of the possible meaning of a piece of software for each individual user?
No. NO! Do not embrace wabi-sabi. That way lies madness. (Or, at least, it will make me really mad.) Sure, perfection is not possible. However, the impossibility of perfection does not negate its importance as a worthy goal. The apparent precision embodied in the word can fool one into believing there is only one way to be perfect and only one definition of the word itself.
Do not think of perfection as a state.
Think of perfection as a process. Perfection is like a journey, with many possible paths and many possible goals, none of which are fully realizable. One chooses one's goal, then one chooses an appropriate path based on the direction from which one would like to approach said goal. Then one embarks upon the journey, always keeping the destination in mind, eventually bringing the destination within sight, however - like Zeno - always knowing one will never quite arrive at said destination.
So, how do you know when you are close enough. That, my friend, is subjective. Did you choose your path well? Or did you hop into the first empty space in the weeds, following a path that barely gets you close enough to the goal to see it with a telescope? Do you even know what your goal is? Have you double-checked with your fellow travelers (your readers) to make sure they even want to go where you plan to take them? To continue to abuse this metaphor, sometimes you have to hack your own path through the jungle. I contend that you can only know when you are "close enough" to your goal when actual readers agree they have arrived with you. Do they now know how to use the equipment or software. Can they perform the procedures without asking others to show them yet again? Without calling tech support over and over? And, most importantly, without giving up half-way down the road? Or do you force them to guess their way around. Do you leave them so far from the goal that they still can't even recognize said goal once they are standing at the end of the path you have made for them?
Far, far too much technical writing these days seems satisfied with the latter. The "technical writers" fill page after page with "content" that barely accomplishes the goal of having words on a page to fill up space. Sure, someone who isn't familiar with the goal may be fooled into believing that the path is clearly laid out, merely because the map has a fancy border and a very stylish X emblazoned on the end of the path. Far too many department managers see that fancy X and sign off on the document without making sure the X is in the right place or that the path is properly constructed. It is almost as if they don't care that the "travelers" - their customers - will be left stranded, with no way of finding the real goal other than going to online forums and begging other users to tell them what should have been in the documentation. It is just as bad as sending your customers out into the deep, dark woods and stranding them there. Leaving them to call out into the darkness, hoping beyond hope that someone will hear them and help them find the goal to which you had promised to deliver them.
Good technical writing creates a smooth and straight path for the readers. A path without bumps and hair-pin turns. A path where you have built bridges over the streams and difficult parts, rather than simply forgetting to mention them on the map. You accomplish this by knowing the product you are documenting better than the engineers themselves. By digging and grilling and conscripting said engineers to help you build the necessary bridges. You accomplish this by using the language clearly, properly, and effectively. You cannot accomplish this by cobbling together a semi-random collection of poorly constructed sentences, filled with incorrect idioms and words that sound kinda-sorta like the word you should have used. You cannot do it by using wabi-sabi as an excuse for your laziness, regardless of how many popular or astute-sounding buzzwords you manage to toss into the mix.
The contents of this post is Copyright © 2013 by Grant Sheridan Robertson.
Introduction to DEMML Powerpoint - I don't know why I never posted this, but here is a link to the PowerPoint I used for my Apiron presentation about DEMML. Below is the text of my notes fo...
4 years ago