Adventures of a #techcomm geek: Go API

Image source: openclipart.org

A couple weeks ago, I got an email from a product manager:

Can you convert these API documents to our format?

Attached were three Weird documents. I let my manager know about the request; he told me to make sure we had rights (the documents were from an OEM, we’re marketing a re-badged version of their product), and to loop in the other writer on this product.

I looped in the other writer, who used to sit right across from me when we had those quaint “office” and “commute” things. While both of us thought it might be best to do it the “right” way—that is, convert the docs to DITA and publish them through our CCMS—we both figured replacing logos and changing names would be good enough.

We both expected the other to pick it up, I suppose, and I was doing other things. The upshot was, I forgot to ping him about it. So Monday came around, and nothing had happened. I groaned at the prospect of using Weird for something more than a two-page HOWTO document, then thought about the scripts I wrote for pulling in documentation through Markdown. “If it becomes too much of a hairball to clean up,” I told myself, “I can always replace the logos and change the product names.”

As it turns out, Markdown is quite adequate for API documentation. There was some cleanup involved, but not as much as I had feared. Global search and replace took care of a lot of it. Most of the manual cleanup was the same kind of thing anyone does when bringing someone else’s documentation into their system—improving topic titles, adding boilerplate… you know the drill. It took about a day to knock the three documents (total of 600 pages, give or take) into shape, and another day to tweak things.

I went ahead and fed the bookmaps to our transform. It was only after I got a decent-looking PDF that I realized: all the topics were still in Markdown. In retrospect, that wasn’t too surprising: the toolkit converts those topics to DITA (temporarily) before processing them. Markdown is a lot easier to deal with when you’re doing cleanup stuff anyway, and I finished that before doing the uplift.

So by Wednesday evening, I was ready to upload the converted documents into the CCMS. The upload tool is more finicky than Morris the cat, and it uncovered a couple more cleanup issues. I resolved those Thursday morning, and we now have clean DITA in the system.

And yay, I didn’t have to touch Weird!

By the way, the conversion scripts are on Github. Just in case you need to do something like this.