We have been misled, but, just like Kool & the Gang, only because we wanted to. We wanted to believe in all those well-balanced, logical, you-just-need-those-three-things definitions. We wanted to trust those clear-cut procedures. We wanted to be confident that those definitive lists of items would take us everywhere we want to go. We were wrong! But that’s ok, nothing here we can’t fix.
I quickly discovered that the few following concepts that I had seen passed around as basic principles of Technical Writing were not accurate, or at least not as absolute as advertised. I’m trying to straighten them out here because I think it’ll help us do a better job and also because I can. Isn’t it what blogs are for? Explaining why everyone else is wrong?
Anyway, here are a number of common misconceptions about Technical Writing. Where did I find them? Mostly in the presentations of Technical Writing made by colleagues, novices and experts. So this is where I may make some enemies.
Technical Writing is for writing (about) technical things
This is really the entry point, the misconception that is created by our name. If someone knows nothing about Technical Writing, they start by interpreting the label. This “technical” misunderstanding is probably one of the reasons why some of us want to use another title for our profession. That is understandable.
For “technical”, the Oxford dictionary gives us:
- Relating to a particular subject, art, or craft, or its techniques.
- Involving or concerned with applied and industrial sciences.
It seems to me, correct me if I’m wrong, that for most of us the second description prevails, and we associate “technical” to both “scientific” and “technologic”; but when we add the first description, “technical” can basically mean “about something”.
So in fact, when I say Technical Writing is not always about technical things, I introduce a misconception, because in reality we always write about a specific subject, or at least we are always supporting a specific activity of the audience, even if that activity can be unrelated with science or technology. In this respect, “technical” is accurate.
What bothers me is when I hear “Technical Writers write about technical things” the emphasis is put on the scientific and technologic aspect of things. I know it because if it wasn’t focused on that part, we would simply say “write about things”, which is the complete meaning of “technical”.
Of course, the fact that we favor dry, factual, bare 100% accurate statements doesn’t help. Always writing like Vulcans is bound to associate us with science and technology. Besides, our profession is thriving thanks to our increasing dependance on technological tools we are provided with, the computer still being on top of that list, and that reinforces this association. I am saying here that we should remember that Technical Writing helps any audience on any topic.
Technical Writing is about explaining complex topics
What we do is especially needed when it comes to share knowledge about complex topics, but that doesn’t mean it “is about” sharing on complex topics. What we have here is a correlation, not a defining trait.
For example, writing cooking recipes is Technical Writing[1]. Cooking recipes can be elementary.
What requires the explanation is not the complexity of the subject, it is the importance of the knowledge in the context of a given activity, for a given audience. Let’s not restrict our writing to things we think are complex. Instead, let the audiences’ actual needs be our guide.
Technical Writing is instructional
When we observe human activity, we realize that any given search for information can be of two types: searching for doing, and searching for knowing. When we want to do, we’re not looking for the same information and not in the same way as when we want to know. This has been demonstrated multiple times in research at least since the 80’s. When novices become experts, the proportion of action increases compared to knowledge collection, but knowledge quest situations still exist. The fact is that we can’t be of much help in a search for knowledge if all we provide is instructions.
When people need to use a tool, even as novices, most of them don’t want to know anything about the tool itself, they just want to do their job quickly and easily. That is why instructions usually answer most audiences’ needs, and that is why we have the feeling that we should stick to instructions. But in some cases, providing knowledge cannot be avoided.
I know that some Product Owners and even some Technical Writers are convinced that a good documentation should contain only instructions. It would certainly be convenient if it was the case. However, I suggest that we verify this with some audience investigation to confirm. If it checks out, good for us! But always know who we help, for what, and when. That will tell us the exact proportion of instructional content we need to create.
Technical Writing is detailed and comprehensive
Describing all we know about our subject and doing it in the most detailed way are two different things but they come from the same feeling that we have to deliver all there is about our topic.
Encyclopedias are fine, and some people are very fond of them (I am one), but it is not needed by our audiences as often as we think it is. And it should certainly not be confused with a defining trait of Technical Writing.
I see two major reasons why we want to go there. First we have a responsibility to provide the knowledge, and whenever we get the audience feedback “this is not in the documentation”, whether it is accurate or not (sometimes people just don’t find the information), we have a tendency to take it personally. We don’t want to see that comment. So we just put everything we have in there and relax: we’re safe! I call that special type of documentation the “disclaimer documentation”.
Second, as an organization that creates awesome products, we want to show off our work. I have mostly worked in the Software Industry and this is very common there: the engineers worked hard to find a way to deliver a given functionality and we want to explain how we have achieved it. I have seen it in electrical engineering too. Usually, in technology at least, most of us are proud of what we have done. We feel compelled to explain it all, in the documentation. I call that special type of documentation the “show-off documentation”.
Well, having too much information never hurts, right? Wrong! When our audience needs a specific type of information, all the useless content gets in the way. It creates noise, confusion, and it steers people towards dead ends when useless information initially looked like it could have been the one they were looking for.
Do not think that just because we provide a search engine, we can safely send our audience digging in any huge heap of information. The proportion of information that can be of use to them is capital. That works for any audience.
- Search or not, we always use context to navigate and to know when to stop. Any audience is very quick in picking up from context whether or not a given body of content is valuable to them.
- The amount of reading or navigating that is required before we get to a point when the information actually helps is capital. We sense and appreciate that “distance to usefulness” very acutely. At a certain point, we decide the cost is higher than the reward and we look for another source.
- When we find information on a given topic, say a functionality, if that information is a description of how the functionality works, it usually doesn’t answer the questions “how can I use it?” and “why should I use this?” If we find the wrong type of description, we will likely declare that search a fail and never come back to it.
- The more we add useless content, the higher the risk of associated issues: ambiguities in the terminology, gigantic structure where everyone gets lost, unmanageable linking system, etc.
I understand that we are very proud of how much content we can produce and deliver in a short time, but the maintenance cost of all that is huge, and for what? For letting our audience down. Remember to provide details for a reason. Describe everything if everything has a use for your targeted audiences. It is not because something exists that it has to be thrown at people’s faces: excess of information has consequences.
The Technical Writer must be a Subject Matter Expert
Now here is a tricky one. There are two opposing positions, but each is compatible with specific classes of situations.
When an organization is looking for a Technical Writer to document new row crop tractors, chances are they will require a Mechanics or Agricultural degree. If so, then what they are really out for is not a Technical Writer with knowledge in Mechanics (or Farming), but a Mechanic with technical writing notions or affinities. Those are very different, each is adapted to different settings, and employers should be aware of that or else there will be much frustration and wasted time.
In our example, both Technical Writing skills and application field skills will have to be acquired, but the situation determines which one we want to be there to start with, knowing that the other set of skills may take some time to develop based on the dispositions of the professional. My opinion is that the skilled Technical Writer has an advantage. In other words, in most cases I would give priority to the Tech Writer profile over the Subject Matter Expert (SME) profile.
In the case of our example, however, I believe we need a field of application background first. Any content that involves making technical/mechanical drawings requires its own know-how, and this is an example of field where Technical Writing and a talent for picking up things is not enough. Still, we should not make “being a SME” a rule.
In my professional journey, I found myself involved in a succession of missions where I had to learn a new field of application, new methodologies and new tools each and every time. It quickly became something I was looking forward to, and I considered that quickly picking up on new things was a core trait of a Technical Writer. However, whenever my designer or developer colleagues or manager seemed to expect a Technical Writer to know everything they know, in addition to everything every audience knows, I was surprised. How can you expect someone to be expert in everything in addition to their own profession? And wouldn’t it be unfair to pay them just one salary?
Some of us do stay in a given field for most their careers, and do become experts in the thing they are documenting. I believe this is not necessarily what we want for making a good job. On one side we have the experts in making a tool (our colleagues), and on the other side experts in something else who need to use the tool (the “end user” audience). We are the people in the middle who translate what’s in the head of the first ones into something that can be easily used by the second ones. After years of working in the same field, we progressively evolve into someone who thinks exactly like the experts in making the tool, and we progressively loose the sense of what needs to be translated.
With practice, research, analysis, knowledge of a given activity, we develop expertise in that activity. Our brain changes, our point of view changes, some concepts that were new some time ago become so familiar that we forget they are there, just like air that we breathe. When we think the activity differently, in a deeper, more complete, much more exact and efficient way, it gives us the feeling we access the Truth, we understand the Reality Of Things, we take the Red Pill: there is no turning back from that. One of the effects is we no longer understand how anyone could not see the Truth. We are much less capable of finding out what could help the end users, especially the new ones. We just don’t see the need anymore, we think it’ll be ok: “it’s not that complicated”.
So, except in specific situations, I think that when we are required to become a SME, our organization doesn’t want us to be translators anymore. We are required to become engineers that are writing instead of engineering. We are kept on the internal side of the border.
If we don’t want that to happen, even involuntarily, I recommend that we compensate all the learning about the field and the tool design with learning about our audiences and their activity context when they use the tool. Another thing that I always do, and that served me well, is taking a lot of notes when I familiarize with the field of application. Every question that comes to me, every click and insight, every discovery, I write it down. Reading that after a few years reconnects me with the issues new users may have and gives me new ideas for content or delivery improvements.
An image is worth more than a thousand words
I am not sure about one thousand, I think some images could be worth just four hundred and fifty words, sometimes even less. On the other hand, you may have noticed that in Technical Writing, one image will cost us a maintenance effort bigger than the maintenance of hundreds of words too. So, when we add an image, let’s make sure that the unspecified large number of words are the ones that the audience needs, because it will cost us, and that cost will increase with time[2]. And I am not even considering translation needs here!
“It is always clearer with pictures” is an argument for more pictures that I’ve heard quite a few times. We could call this an opportunistic justification. Sometimes, an image clarifies things, sometimes it is even essential to have images, but it is not systematic. The “always” argument is used because we don’t want to make the decision of whether or not we include an image, and we don’t want to make the effort of finding another way to clarify things if we realize an image won’t help.
There is such a thing as too much images though. I have seen it! It extends our content over pages and pages[3], and if there is only little change from one image to the next, it will create so much confusion that any reader will have to dedicate much more focus energy on following the progression than what would have been necessary with other means of explanation.
So, just like everything else, add images if you have a good reason. We can discuss for years on exactly how many words a picture can be worth; if those words help no one, they’re a liability.
I’ve recently read an interesting post by Sarah Moir about how to deal with pictures, and I have a very nice anecdote related to what she explains. I’ll make a specific post for that soon, stay tuned.
Technical Communication is everywhere!
That one is accurate.
Not a misconception. Tech Comm is everywhere. Labels, signs, arrows, basic instructions, whatever you do, you’ll find help. Note that most of this help does not involve “complex” subjects, is not overly “technical” and doesn’t need to provide much detail.
While we’re here…
I could have added this to my post “What is Technical Writing?”, but that one is too long already!
I have watched and re-watched a number of videos about Technical Writing to write this post. Here are my two favorites, because the definition they propose is very close to mine (“helping someone to do something or make a decision”):
https://www.youtube.com/watch?v=shCcP2auxkk
https://www.youtube.com/watch?v=juIo1NKatwQ
Those videos are also the two shortest and the two oldest of the set. Are we getting carried away these days?
[1] We are giving instructions and sometimes suggestions, with a number of facts, for people to follow or not, so they can use the help they need to cook better: recipes are legit Technical Writing.
[2] Have you ever noticed how, when something new is introduced in a product, we spend minutes to check if some of our textual content needs an update, and hours to check if our image content needs an update? That will happen each time changes are introduced.
[3] Some people believe that pages don’t exist anymore. As soon as there is too much information to display at once on a screen, we have to scroll or slide, and we need to display the same cognitive effort as with pages.
No comments:
Post a Comment
What do you think?