Don't be daunted by technical documentation requirements

Requirements gathering is one of the most challenging steps when creating technical documentation. In the IT industry, it can sometimes be a daunting task that entails interviewing and communicating with some of the brightest minds in Technology.

Although these very bright minds come attached to some of the nicest people on earth, the technical documentation requirement poses a challenge for the interviewing Technical Writer (TW) as we need to find the best way to extract that information from Engineers, Cloud Architects, Software Developers, and other very tech-savvy professionals to produce high-quality documentation.

This article will help you navigate that sometimes terrifying step in the technical writing process by providing first-hand recommendations and insights obtained after working with a variety of technology professionals from blossoming startups to massive tech industry leaders like Google, AWS, and Cognizant.****

Who am I?

---

****I am a TW Manager, currently working with Cognizant, supporting Google. I have worked as a manager for over 15 years and transitioned into Tech Writing seven years ago. I have a rather deeply rooted love for technology, writing, and the English language.

The technical writing process

Before diving into my recommendations regarding the best way to handle technical documentation requirements I’d like to lay the foundations for our common ground. This is important because some of you will know this information inside out while others will not.

According to the book Technical Communication Today, the technical writing process typically consists of five stages:

1. Planning and Researching
2. Organizing and Drafting
3. Improving Style
4. Designing
5. Revising and Editing

This article will revolve around the Planning and Researching stage.

Planning out your project

During the planning and researching stage, you should accomplish three tasks:

1. Analyze the rhetorical situation
2. Understand the startup
3. Refine your purpose

These three steps all share a common thread, which is that they can all be traced back to the effectiveness of your initial technical documentation-gathering process.

Analyzing and understanding the rhetorical situation of your document entails gaining a firm grasp of its subject, purpose, audience, and context of use. To define the rhetorical situation, start out by asking the 5 Ws and 1 H questions: who, what, why, where, when, and how.****

● Who are my recipients, and who else is involved with the project?

● What do the recipients want and need, and what do I want and need?

● Why do the recipients need the information in this document?

● Where do they need the information, and where will they use it?

● When will the information be used, and when is it needed?

● How should I achieve my purpose and goals?

Asking these questions is the initial step toward creating your deliverable.

Additionally, to refine your understanding of the rhetorical situation, in my experience, there is an extra step that makes a big difference in the overall quality of your documentation, and that is spending some time lost in thought while simultaneously taking notes on the following four elements of the rhetorical situation:

● Subject. What is the document about? What is it not about? What kind of information will my readers need to make a decision or complete a task? What is the scope of the project?

● Purpose. What does this document need to achieve or prove? Why do my recipients need this document and what do they need to know?

● Recipients. Who are the readers of this document? What are their specific needs and interests? What are they looking for in this document?

● Context of use. Where and when will this document be used?

Defining the rhetorical situation is an essential step that will save you time and effort because you will avoid dead ends, unnecessary revision, and writer’s block.

Performing startup research

Up next is startup research, and this is where the fun begins. Before online search engines, finding enough information was usually a writer’s main challenge, but not anymore. As an added step to your internet search, you will want to read books on the subject of your document, take a couple of courses, and do everything and anything possible to get your hands on the necessary material to level the playing field for document preparation. This might sound like a bit too much, as in over-preparation, but will come in handy when it’s time to interview those super-successful and super-accomplished SMEs and stakeholders.****

Interviewing highly-technical SMEs

Throughout the planning and researching stage, the TW has the opportunity to work shoulder-to-shoulder with and interview engineers, developers, industry gurus, and other highly technical SMEs. Let’s focus on that interview with that larger-than-life SME that created a major technological feat like the four pillars of the AWS Well-Architected Framework, just for the sake of giving an example.

Interviewing SMEs with the purpose of gathering documentation requirements can be a terrifying step for junior and sometimes even senior TWs who may feel intimidated by the idea of interviewing SMEs and other stakeholders who possess an extremely high level of technical proficiency, and who, on top of being such great experts, work for the biggest and most influential companies in the world.

I would like to share with you some of the techniques and tactics I have adopted to streamline my document requirement-gathering process, but for us to talk about that we must first discuss the “curse of knowledge.”****

Defining the curse of knowledge

According to Steven Pinker in his work, “The Source of Bad Writing,” the curse of knowledge leads writers to assume their readers know everything they know. This sort of generalization happens because it’s difficult imagining what it is like for someone else not to know something that you know. Psychologists sometimes call it mindblindness. This mindblindness affects all of us, as we often find it difficult to imagine what it is like for someone else not to know something that you know. The TW can come across the curse of knowledge when approaching an expert for a documentation requirement session, and the expert has been working on the same task or field for a long period.****

Defeating the curse of knowledge

****SMEs who suffer from the curse of knowledge sometimes assume that the people around them possess the same knowledge as they do and, in turn, will speak about the topic at hand abstractly during the documentation requirement-gathering interview. These types of SMEs may say things like, “Please document our architecture pillars because they are crucial to this document. If you have any questions let me know,” instead of finding out if the TW possesses prior knowledge of the topic to ensure both parties see eye-to-eye. If the TW needs more info, then the SME can offer a high-level explanation and progressively move on to more granular points of the documentation requirements.

If your SME doesn’t take steps to bridge the gap between their knowledge and your understanding then you can significantly do so by asking simple questions about the topic. Use and suggest the usage of concrete language, paraphrase what the SME has explained to you, and compartmentalize the information received. Explaining your tactics to the SME can also help since the SME will respect your effort and will most likely deliver a simplified version of their requirements.****

What if it’s the Technical Writer who suffers from the curse of knowledge?

Just as with SMEs, TWs may tend to do the same at one point or another. We sometimes think that every single SME we interview is an expert in the technical documentation requirement-gathering process and therefore jump right into the requirement-gathering interview while neglecting to ask if the SME has previously been involved in a requirement-gathering process.

The TW assumes the SME knows all about the process, when in fact, it’s a common mistake to skip that verification tactic. In turn, TWs might end up losing opportunities to leverage those interviews. This nuisance can be surpassed easily by creating a template that includes a series of questions to be used at the beginning of the requirement-gathering interview or process. These are questions like:

● Is this the first time you’ve had a documentation requirements meeting?

● What do you know about the technical writing process?

● What would you say is the most challenging task/feature/situation we aim at documenting for this deliverable?

Basically, we want to reach a point where the SME and the TW can be at the same level of understanding, each sharing a high-level comprehension of the technical documentation requirement process and its nuances. This allows the TW to find the best way to communicate and comprehend the subject matter, ensuring the production of high-quality technical documentation.

How do documentation requirement-gathering interviews differ for startups vs enterprises?

In my experience, the tech documentation requirement-gathering processes are quite different for startups vs enterprises. However, I believe that one of the main differences is that most SMEs at companies like AWS, Google, and Cognizant, to name a few, have been involved in documentation efforts much more often than SMEs who work for startups. I have been in situations while creating software documentation for startups where the documentation knowledge base is an area of opportunity.****

The Technical Writer as educator

Although I know that TWs wear many hats, the following information is based on my experience and by no means represents any sort of universal truth.

While working for startups, the additional role the TW plays is that of an educator, someone who will establish a documentation process for the company and will therefore have the opportunity to pass on the knowledge of the technical documentation process.

While working for more prominent companies, the additional roles the TW plays involve working with SMEs that have been through the technical documentation requirement process quite a few times. While working with SMEs in big companies, the TW can feel more at ease regarding the education necessary to provide to the SME. However, the role the TW has to play while working with industry giants is that of a highly-skilled interviewer, being an incredibly thorough TW and Project Manager (PM) who can capture all the requirements accurately and who will also steadily follow up to keep the SME in the loop throughout the documentation creation process.

Nevertheless, we must always keep the curse of knowledge in mind, always taking necessary steps to ensure both the SME and TW are on the same wavelength. Because only by knowing so can we be confident that our documentation process has been done thoroughly, considering all the recipients who will benefit from solid, well-explained, high-quality documentation.

In a nutshell, TWs have to wear many different hats and need to have a large assortment of tools in their arsenal. I hope this information provides you with additional tools that you can use to become a more well-rounded Technical Writer.__

Carlos F. Arriaga is a technical writer with a love for the English language and a passion for the technical writing process. With a master's degree in engineering and experience working with several prominent tech companies, Carlos thrives on leveraging his abilities to help educate the technical community. A self-described geek, Carlos enjoys studying Cloud Technology as much as Star Wars.

__