Technical communicators are a liaison between machines and humans. They help humans interact effectively with their machines. 

The tech writers (another name for the technical communicators) help the developers and subject matter experts by curating intricate information about the product for other developers or for the end users. In the absence of technical documents, they (devs and SMEs) would be majorly blocking their calendars to provide support to customers or training the newly onboarded coders, thus preventing them from concentrating on their work. 

Note that the developer and user documentation are completely two different pieces of art that the technical communicators produce. The developer documentation is designed to let the developers look directly into the code while the user docs hand holds the users of the product through the various flows of the product.

The life of technical writers is like that of ‘Hunters and Gatherers’ where they are always hunting for the developers and SMEs for knowledge sessions and gather whatever information they can from the mail threads and chat threads. The product is heavily documented in these two sources and the writers have to wade through to collect any useful piece of information that can form the part of the piece they are writing.

After finding who their readers are and what they want to read, the writers are tasked with presenting their information in a way that is quick to find and crisp to read because technical documentation is not a fairy tale book that parents like to read to their children in bed. Technical writings are read for a purpose and once the purpose is met the readers do not recommend it to their pals to read for pleasure. Therefore, the architecture of technical information should be such that the readers can quickly find what they want and have enough information as required. Not more, not less!

Mentioned below are the five Ts of technical writing that can help writers to effectively design their piece which is highly consumable.

• Targetted
• Source of Truth
• To-the-point
• Taxonomic
• Timely updated

1. Targetted

Before starting to write any documentation the writers should have a clear understanding of who their readers are. Finding out the target readers is an important exercise in documentation planning.

The architecture of the documentation and what information goes there depends greatly on who will be the readers of the documentation.

For example, try to visualize the different documents that can be written to explain the “water cycle” to a class 10 student and a meteorological officer trainee.

The class 10 guys just need to learn the concepts while the met officer trainee needs a greatly detailed explanation of the phenomenon with respect to various geographical locations.

Another example – writing a document to inform how to perform a Google search to your granny and writing a document to inform how a Google search is performed to a trainee engineer who has just joined Google.

Dear Granny will be just given the steps to type keywords in the search bar and press enter while the trainee engineer will be told what happens when the search button is pressed and how the algorithm works.

A broad classification of the documentation that can be written:

• Developers
  • API Documentation
  • Documentation of the code with sequence diagrams, flow charts, and swimlane diagrams
  • A readme with a brief description of the project/product and installation / access instructions (if required)
• End users 
  • Quick start guides
  • How to guides
  • Product manuals
  • Procedures 
  • Troubleshooting documentation for admins

2. Source of Truth

The documentation should be a source of truth. That means it should be thoroughly reviewed for facts. Only authentic and verified information must go into the documentation. 

Unverified information, “maybes” and, “i thinks” will only confuse the readers. It diminishes the value of the information and thus the readers lose trust in the documentation. This is the worst thing that can happen to a technical writer. And, all the efforts that have been put into writing the documentation may go in vain

The writers should compulsorily get the documents reviewed and verified by the subject matter experts. The management should be equally cautious to get the documents verified and publish them only after getting the required sign-offs.

The writers should provide reference to the source of information, wherever possible.

3. To-the-point

Technical documentations are not thriller novels or story books that people would like to read in their leisure.

For this reason, it should avoid being over-descriptive and wordy. The writer should put a full stop as soon as the purpose of writing the piece of information is met. At the same time, no important, useful, related information should be missed. The writers may know a lot about how stuff works but they should restrain and write only what will help the reader achieve their target. That’s it!

For example, while writing the procedure to perform a google search, it is enough to write “..enter your keyword and press enter. The search results are displayed. You can browse through the pagination at the bottom of the pages to view results on other pages (this is the extra bit of information that we recommended above)”.

It is irrelevant to write “…as soon as you press enter after entering your keyword the spiderbot/crawlers crawl the world wide web to fetch all the results relevant for your keyword. And they bring in front of you thousands of information relevant to your search” 

The writers are not tasked with igniting love for the crawlers in the heart of the googler so as to overwhelm him with the thought of how hard the crawlers work to fetch what they want.

4. Taxonomic

Taxonomy is the science of classifying organisms. It is used in information architecture with respect to classifying the information and setting up a hierarchy. 

The job of the technical writers does not end with gathering and writing information. Even if the document is well-targeted and crisp, it will lose sheen if not presented in a well-structured architecture. 

The information architecture decides how the documentation is presented to its readers and which topic should be written where.  A well-structured document has the information arranged in proper hierarchy. This makes it easy for the readers/users to spot their piece of information without much effort. 

Remember! Unstructured documentation creates frustration in the minds of the readers.

5. Timely updated

An important stage in the documentation development life cycle is the maintenance of documentation. It comes after the documentation is planned, written, reviewed, verified, and published. 

The product changes over time and with it the documentation must be updated. The developers and SMEs can set up a trigger so as to alert the writers about any update happening to the product.

The writers can proactively scan the release notes and feature/enhancement tickets to find out about the changes happening in the product.

Beware! Outdated documentation will again cause the readers to lose trust in the documentation. 

Conclusion

To conclude, great documentation can be a life saver at times. A great writer is not just the one who writes well but the one who empathizes with his readers and understands their needs fully and writes to solve their problems.