The last time I sat to write about something, I discovered that I very-well knew what I knew about the topic and what I never knew about it. The part that intrigued me, was finding about what I never knew I knew, and what I did not know I didn’t knew. As Confucius puts it, true wisdom is knowing what you know and knowing what you don’t know. But, about two and a half centuries back, it was comparatively easier to list what one did not know than to list what one doesn’t know today.
When I am preparing, editing documents, I stumble upon numerous examples of what one knows that he/she doesn’t know (Have patience, I have a lot of examples below). As tech writers, having knowledge of the product doesn’t solve our problems. The question of what to include and what not to include still remains unanswered. Although, we need to write with the reader in perspective, but that doesn’t mean we should include everything that a user might want to know. If I were to use the wisdom bestowed upon us by Confucius, I would try to use my experience, which speaks louder than (here, quite literally) “words”. For the user documentation, the trick, as I see, is in knowing what the user “needs to know” not what the reader “wants to know”.
For this blog, I have listed a few observations that have helped me in tech writing. I assume that you already know what I know. But, again, who knows!
Brevity is the soul
Brevity is the soul of (not just) wits. Small sentences attract readership, assure greater recall value, and are easy for the user to follow and implement. Studies show that only advanced readers can read more than 30 words in a sentence. So, assuming that you write for a layperson, write small sentences (I know you did not know this). Avoid using sentences that begin with “Here, it is to be note that…” instead use “Note that…”
Avoid noun stacks. Sentences that talk about “The impact of the amplification of the technically advanced components of a software” can and SHOULD talk about “Effectiveness of intuitive tools”.
Also, using complex words doesn’t mean better documentation. Simply, better documentation means better documentation. Brilliance, as they say, is in simplicity. Your vision is to be understood; irrespective of the complex features of your product, you must write in simple terms. Phrase and rephrase sentences to ensure brevity.
Words are all I have
Albeit you cannot assume the scholastic quotient of the user, you must, no matter what, avoid unnecessary words/sentences. Look the way I have bracketed “no matter what” in the previous sentence. Placing it outside the bracketing commas will not contribute anything to the sentence, and hence the words are set apart. For a user document, things are only more formal and compact. Also, avoid using words before checking for their meanings and relative usage.
I recently read in a user guide, “The following steps are obligatory”. The writer tried to be creative, only to ruin things. By obligatory, the writer meant “mandatory”, only if he/she had checked the meaning. Funny, but sad.
Another example is of that of a cell phone manual, in which I read about pressing the “Save” button to save a contact. Had that been the first user manual for the first cell phone on this planet, it would still have made sense for us to write about pressing the “Save” button to save records. Obviously, nobody will press “Cancel” to save records. That’s hard-earned judgment called experience! And you knew that you knew this.
Stuck between the call of the product and the call of the process
At times we get a little too verbose and repetitive. Too many words, too many times to describe something that is but understood. For example, in an Administrator Guide, the descriptions of setting up User Roles vis-à-vis setting up User Groups will almost be the same. In such cases, repeating information will only help. We might know that the user knows about it, but that should not stop us from mentioning about the scope in the guide. This is the call of the process.
Another example is of that of providing information about setting up dashboards for various modules of your ERP system. The procedure for setting up a dashboard will remain same, irrespective of the module you use. In such cases, we will provide information pertaining to setting up a reporting layer in the preceding chapter, and provide cross-references as we need. This is a product call.
Make friends with friendly documentation
A user might recall a very technical point, but may miss out on the very basic details. Use your intuition when you are referring to GUI elements and abbreviations. Words like Customer ID can be easily referred to as Customer Identifier, “user credentials” can replace “log in name” and “password”, and MTL_SPMT_STS can be replaced with “material shipment status report”. Use friendly terms.
The most common mistakes that tech writers commit is that they stop thinking and start recording. Documenting features can be done easily, the difficult task is of getting understood. I do not mean that one should begin writing “Ok” to denote the “OK” button. What I mean is, intuitive names give more meaning to a users’ understanding of the product. In my earlier posts, I have told that technical writing challenges us to bring the best of two worlds together: Technology and writing. Having intuitive words, thus, brings the understanding of two minds together: Yours’ and the users’.
Make research the mother of invention
To date, there exists a huge gap between what I perceive I know, and what I actually know; same goes for the user as well. Technical documentation may not bridge that gap, but will definitely help build bridges. Also, it is possible that you may never get to know how much you actually know or don’t know, but that should not hinder your work as a tech writer. Make research a part of your profile. Research and read about topics you do not know. You might come to know something you didn’t know you knew! And that’s that.
Farther I shall go, for I have words to keep
Telling more, just because you know it all, is another common error in tech writing. Tell only what is needed. The long-term vision for any company is necessarily carved out by the documentation, who although are the backstage players, work perfectly in line with the company’s growth plans. A happier company has fewer consultation calls, more demos and leads in prospects, more compact content, and lesser worries.
Find new techniques to apply documentation to: Come to know what you don’t know. Use single source publishing, keep documents updated, circulate copies of documents to the consultation staff (they don’t need to keep customers waiting over phone calls, while download a copy of the guides from the web site.), bring new features to face the customers (they too are testers), or create a wiki (user-generated content is equally important).
Final words
To bring the thoughts together, I will reiterate what we have covered so far. Keep sentences short. Repeat the description wherever needed: It is possible that you might tell users something more frequently than they are supposed to know, but you will not tell them anything more than they are supposed to know. Bring in words that are intuitive. Generate interest in readers. Keep them informed. Now, these are some of the points I knew were either known to me, or what I have come to know.
I know that I don’t know more than I don’t know. And I know that I might not come to know everything that is not known to me. As an example, my thoughts intrigued you. Although simple, the sentences were odd, confusing, but enjoyable. And, it wasn’t that complicated, still, before reading you never felt that you knew most of it!
And, amidst all the wisdom, I will try to answer the question: What to include or exclude is subject to one’s wisdom. So be wise.
The Wordsmith 