Keith Johnson was the key speaker in the fourth session of the Technical Writing Project Lifecycle workshop organized by Advanced Technical Writing Group in association with Metapercept Technology Solutions and Oxygen XML. He has over 25 years of experience in technical communications.

 

In this session, Keith shared insights on the macro and micro aspects of technical documentation. He elaborated on the steps that a technical writer ought to take before and after the documentation process starts.

 

The macro aspect of technical documentation covers the process to follow before you start writing your document. The macro technical writing steps are basically to ensure that you have an understanding of the project with access to reliable resources.

 

1.      Sizing:

 

The first and foremost step is to understand the size of the project. When you are given a project for technical documentation, start by assessing the number of steps, number of endpoints, etc. to understand the scale of the project. In this phase, you deal with the management of the organization who are not much aware of the technical aspect. Learn about the scope of the project from a business angle.

 

2.      Scoping:

 

In this phase, you will meet people who understand the technical aspect of the project. You can assess the viability of the size of the project by checking with project managers, developers, etc. These people understand the nuts and bolts of the process you are required to document. Therefore, the audience and complexity assessment take place during this phase.

 

If there is a mismatch between sizing and scoping, you should go back to the management and discuss the same with them. Tier 1 documents can be scoped easily as it is for the general public. Tier 2 documents are aimed at engineers, architects, etc. and, hence, need extra attention.

 

3.      Information Resources:

 

After you are done with sizing and scoping your documentation, you need to find credible information resources. Generally, a Subject Matter Expert (SME) is assigned to technical writers for providing all the information required. These SMEs possess in-depth technical knowledge and can help you in generating documents that meet both business and technical goals.

 

When interacting with SMEs, you need to showcase how you will add value to the process with your work. It is to ensure full cooperation from them. For this purpose, you need to develop salesmanship during your career.

 

4.      Question Categories:

 

You need to ask questions, the relevant ones, to get more information from SMEs. Before you start brainstorming, go through the 5Ws and 1H process to lay the structure of your understanding of the process before the SME interview.

 

5 Ws and 1 H are:

 

What?

Example: What are the use cases you will be referring to?

 

Who?

Example: Who will be approving this task?

 

When?

Example: When should I test this?

 

Where?

Example: Where shall I go to see what developers have built?

 

Why?

Example: Why is this documentation important?

 

How?

Example: How do I log in and configure for testing on my system?

 

5.      Brainstorming:

 

Brainstorming might seem an obvious thing to do. However, many people tend to forget about it or skip it on purpose. Before you underestimate the importance of brainstorming, you should remember that SMEs can provide you with the information required but can’t do your work for you. You need to have a list of questions prepared before you meet the SMEs.

 

So, gain an understanding of the topic before jotting down your questions. If the process you are documenting is entirely new, you can gain theoretical knowledge about the topic. This, in turn, helps in framing relevant questions for the SMEs.

 

6.      Interviewing SMEs:

 

After gaining a deeper understanding of the topic, you can now write down the questions you need to ask the SMEs. The answers to these questions should be able to help you to add substantial content. Ensure that SMEs are awarded points for their time with you. Since the SMEs are loaded with their own work, a little recognition for this task will help you to schedule meetings with them.

 

7.      Concept Refinement:

 

You may sometimes find that the topic assigned to you by the management requires modifications or is outright wrong. The gap in understanding between the technical team and the management requires you to work hand in hand with your manager and lead SMEs. You need to take small steps and work on a granular level if you are writing about entirely new technology.

 

8.      Information Latitude:

 

As technical writers, you might become ‘limited’ SMEs as you work with managers, architects, SMEs, etc. It will help you to gather more information than required. You should make sure that there is enough content to start the documentation process. Further, you should have enough information latitude so that you don’t fall short of content while documenting.

 

9.  Calling on the Web:

 

Although you will have access to information through SMEs, you might need to research on your own too. This happens when the SMEs are new to the organization or the role. In this situation when proprietary resources fall short, you can always use the internet to become your own SME. And, most of the time, if you are willing to go the extra mile, there is just enough information available on the web.

 

10.  Diagramming:

 

After sizing, scoping, interviewing SMEs, researching, and gathering enough information, do not jump to the writing phase. Before you start writing, create a logical flow of the information by walking in your reader’s shoes. Prepare a diagram to represent the structure of the document.

After this, you can start writing.

 

Conclusion

Do not start writing your document as soon as you get the project. Start with the necessary preparations to understand and gather information. You must ensure that you have more information than required before you start writing. Finally, you should have a logical flow of the information to complete the documentation.

 

Very often technical writers skip most of the macro technical writing steps. However, it shouldn’t be avoided at any cost. Have you ever seen a band perform directly at a concert without sound checks, warm-ups, etc.? It is the same for technical writers too!

 

In the next part of this blog, you will learn about micro aspects of technical writing! If you are an aspiring technical writer or have any technical writing requirements, feel free to talk to our team. 

 

Author: Ruchi Rai, Technical Writer, Metapercept Technology Servcies LLP