Search This Blog

Thursday, September 14, 2023

When you don't have all the pieces

When you create documentation, there are three fundamental questions you need to ask.

1. What is the thing you're trying to document?
2. What kind of document are you writing?
3. Who is the audience for this document?

If you get answers to these questions and find the key Subject Matter Experts (SMEs), you're on your way to creating good documentation. But let's be honest with ourselves, even with this information, there's a good chance that you'll still have missing pieces. What do you do then? 

If you're in a circumstance, where you can test the product, say software or API calls, then you can probably fill some of the missing information. But not all technical writing circumstances are the same. Sometimes, we're detached from the subject we're writing about because we're not able to test a product. Going on a limb here, say nuclear technology. It doesn't have to be this extreme. But it could be just simply no way of testing out your subject or product. So what do you then?

One thing you can do is be persistent. As you talk to the SMEs, ask your questions along the lines of the fundamental questions you've asked initially. When SMEs are stumped from your questions, you can ask them who would know. They might direct you to another point of contact or get back to you if they need to dig into this. In any case, finding the missing information for a documentation isn't impossible. It just requires persistent. 

The worst that can happen with documentation, is that you can't write it, because the information doesn't exist and maybe the subject just a concept for now. And that's a planning issue beyond the scope of your responsibilities. Aside from this, if you're persistent you can find the missing information.

It reminds of the game Chrono Trigger with mysterious gray chests scattered throughout in different places and time. When you try open them, it would play a song and a dialog box tells you a mysterious force is keeping it locked. You can still play the game but it seems like something's missing when you can't open these chests. These chests stay locked until you charge up Marle's perdant and that's when you can open these mysterious chests.  

Like the way you need to charge up Marle's pendant to unlock these chests, you just need to find that piece of information or point of contact that help links the missing pieces together. Creating documents can be an interesting quest.