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.

When There's a Need, Write, but What If...

"See a need, fill a need."

That's good advice with innovation, providing goods or services to others, and writing, especially with technical writing. 

Whenever I've ran into different things or got into conversations with people whether it was about a user interface (UI), an API endpoint, how to maintenance or install a part, or a procedure, if there were no documentation on them and I was able to do so, I would write something to fill that need. Or, if the documentation was poor and if possible, I would try to improve it.

I took this advice of seeing a need and filling a need when I wrote my novel, The Unlikely Messenger. At the time, I found no one out there who wrote something similar, especially with the challenges the main character had to face. The theological answer for my character's condition were either lacking or weren't really acceptable (at least for me). So what I did I do? I slowly over 10 years wrote a novel. Looking back, I don't know whether I should have written the novel. Maybe there was no need to do so. But what's done is done. And, I'm fine by it. In the end, I'll have answer to God about the book.

But what happens when there's no need to fill? Or, what happens if there's someone else already wrote similar? So they seemingly filled that need.

The short answer: Don't write it.

Yes. That's right. Don't write. You're wasting your time and energy. Why be just another voice saying the same thing, especially if you don't need to? You don't see, or you shouldn't see, two or more documents explaining the same thing about such and such. So, use your writing for things that don't exist yet. 

Besides, you can always look to find needs to fill. It just may not be in the places you're looking at. So, look elsewhere. But if you can't find those needs yet, then wait. If you need to, do something else while you wait. If you also feel like you need to, freewrite or journal. But if there's really no need to write something, then don't write it. (But, if you feel like you have a unique idea, then by all means write it out.) In the meantime, what can you do is observe what's around you and listen to what others say. When you do that, you'll end up writing something eventually.

As for those who've written something already, if you think you can say it better, do so. Otherwise, step aside and just direct or refer others to that piece of writing or documentation if they're looking for such and such. Writing for ego's sake is empty and shallow. Been there, done that.

But I suppose if we only wrote what's necessary, then that would probably eliminate most content out there. Maybe this blog belongs in that pile. Hmm.

Demystify the API

What is an API? A string of random letters floating in an alphabet soup?

API is more than an obscure acronym in the ocean of technical terms. It's actually becoming very relevant in some quadrants of technical writing.

API stands for Application Programming Interface. It means basically means a set of steps, routines, and procedures to create software or applications. 

Where technical writing comes into the play with APIs is that documenting how to use the programming language to create or modify a software or an application. You may have heard the terms "API Guide" or "API Manual." If not, that's okay. I've only heard the term a couple of years ago. 

From what I gather, these types of documentation are basically user manuals for software or app developers so they can create their programs. 

There are also some terms we should know when it comes to API documentation.  I don't want to say that these cover all there is to API, but you may run into these terms when you're either looking for your next gig or when your company decides to create API documentation. They are REST, SOAP, and Endpoints.

REST (REpresentational State Transfer) API
   
REST API doesn't mean procedures on how to create an application to help you sleep (though, I'm sure something like that out there exists).

REST API (or REST-ful API) means it's an API that based on the nuts and bolts and the structure (software architecture) of the Internet. This is not based on some markup language, like HTML or JavaScript, or some standard. It more of a style of an API. I'm not even sure if this is completely accurate to say. There's a reason why: REST-ful APIs depend on the organization that creates them.

Some REST-ful API can be done in JSON (JavaScript Object Notation), XML, or even HTTP. Again, it's a style or architecture an API is presented in. (API writers feel free to give some comments)

Now another type of API that's easier to pin down is SOAP API.

SOAP (Simple Object Access Protocol) API

SOAP API is more clean cut to define than REST API. No, it's not a way to create applications to produce bars of soap (again, there might an app out there to do that).

SOAP APIs are set of steps to create applications based on an XML Infoset. I guess it's good to know XML other than working with it in a structured authoring environment.

Endpoints

Another thing to note about API documentation is something called Endpoints. I have only heard of this term in the past a couple of months when I did an API document for a healthcare company.

An API endpoint is basically a procedure or a method of how an API will run.

You would typically see this with an example of code in the document. Then before or after the example, you would have the name of the method, say a command or a parameter, and the definition of it.

API endpoints depend on the organization that determines them.

Final Thoughts

It seems, at this point, the line between software developer and technical writer are blurred. Based on what I have seen, it seems that companies who are looking for API technical writers are basically looking for developers that can write. Many times that they looking for candidates who have experience with programming languages.

My question to them is, why look for technical writers if you can just use programmers to do the documentation? The only thing I can think of is that API documentation is fairly recent and somewhat uncharted for us technical writers. Whether API docs will be something for technical writers to do, or will finally just reside in the realm of software developers remains to be seen.

In any case, if you want to try your hand at API documentation, don't be disheartened. You can pick up programming languages either by being self-taught or taking courses.