Photo by Caleb Woods on Unsplash — This cat is me. I am this cat.

Managing Technical Documentation, The High-Level Junk

Random thoughts from a not-that-qualified person

I remember being new to technical writing and being out of my depth when it came to the behind-the-scenes architecture of how things got from my inbox all the way out to the web for customers to consume. Sure, I knew what XML and HTML were, but how in the hell they worked, I knew not. I had no idea what Markdown was. I knew about, and could parse, very few programming languages. If you had told me that one day I would use Linux, Docker, Git, Markdown, Atom, and Docusaurus to generate documentation I probably would’ve just blankly stared at you for eternity until you eventually wandered away, confused, and perhaps a little scared for my mental state.

I didn’t learn any of these things in school, you see. These are all just practical add-ons to my code base that I’ve picked up over the years out of idle curiosity and a desire to do things more efficiently (because I am lazy). I also had the good fortune to find myself at certain companies where this kind of knowledge was abundant, and I formed relationships with people who were patient and kind enough to help me. Dumb luck, curiosity, and other people are the only reasons I know what I know now.

I was an English major in college. The inimitable John Mulaney quote: “I got a degree in a language I already spoke for reading books I didn’t read,” pretty well sums it up. I learned some valuable stuff in college. Mostly how to do some less than savory things that I won’t cop to on a blog post about tech writing (hello employers), how to show up late for class and still pass, and that watermarking pictures of Bill Gates on your assignments will endear you to your favorite professor forever, because she will write STOP THAT! B- in bold red ink at the top and then draw a smiley face next to it, essentially telling you: “Keep doing this, I find it funny,” which I sure did take at (smiley) face value. She loved me. I still send her holiday cards with Bill Gates’ face watermarked on the inside. I’m probably on a watchlist of some kind, but the bit doesn’t die just because I haven’t been in college for *mumbles numbers unintelligibly* …. *sobs*.

Anyway — of all the stuff I learned in college, plenty of which was actually useful, the most important takeaway was tenacity.

If you show up and put in the work, provided you have enough credits and good enough grades, you will graduate. If you don’t know how to do something, double down on figuring it out. There’s this fitness trainer I follow called Da Rulk (yes, that’s what he goes by… and looks like, come to think of it). He has a saying, “Always can,” which is a shorthand way of saying the Hawaiian phrase, “If can, can. If no can, still can.” It’s the same sentiment. Tenacity is important. Show up, do the work, and you will improve.

I tell you this about tenacity because if you are a baby tech writer interested in learning more about the behind-the-scenes glue that magicks your docs into existence, allow me to first indulge in a little explainer that might drive you to drink. Have some Tito’s handy. Do you a Google on any of these terms and you will find way more accurate descriptions — but this is my understanding of them from *mumbles numbers unintelligbly* years of experience in the technical writing field.

• Information Architecture: It is what it sounds like; the architecture of information. It’s the organization, structure, and design of the digital landscape — but it’s a broad term that can apply to something like your company’s knowledge center, which probably has multiple backend endpoints feeding into it, or to multiple complex enterprise systems that all need to integrate together seamlessly. At any rate this is usually something that somebody manages. Information Architects are usually part of dat IT crowd. In my experience, they’re CompSci nerds that just want everyone to leave them alone and let them do their dark DNS deeds. BUT, at some companies, Information Architecture can refer to one very specific piece — the architecture and integration of the docs component. You will see it both ways on LinkedIn. However, IMO, the latter is actually more of a next bullet thing.
• Content Management or Content Management Strategy or Content Strategy: Sweet baby Jesus take the wheel… Can we have a bit of consistency in naming please? You might see these terms used interchangeably with Information Architecture, but they are not the same. Content Management (not a CMS — we’re not there yet) involves sourcing, maintaining, versioning, and updating your content. And yes, I believe in the Oxford comma. This might entail using a Content Management System (CMS) to both edit and house your docs. This might entail using XML/DITA with a decoupled CMS and homegrown tools. This might entail using a docs-as-code approach because you want developers to contribute to the documentation. How these tools and systems integrate together to serve up information in the desired place is Information Architecture. Strategy is, as always, how you plan on making a thing happen. So a Content Management Strategy should take into account the tools and systems already in use, it should employ a needs assessment to figure out certain requirements (Do you need to show versions or variants to customers? Are you writing for translation? What about accessibility? etc…) and then it should come up with a plan to deploy the agreed-upon tools and systems to achieve the desired results.

Content Manglement

I’m going to speak to just the Content Management piece here, because it’s a rather large and complex beast, and my neck hurts, and I’m tired. I will also link to some further reading on the subject and a Marc Rebillet video later, if you’re interested. Who am I kidding? You’ve already stopped reading haven’t you.

Fine, I will scream it into the void then.

Content Management for technical documentation begins with really just three things that help you do all the other things: the thing you use to grammar all over the docs with, where you store yo’ stuff, and the output. Once you figure out these things, then you can dedicate time to planning and processes and maintenance and whatnot, or how you’ll include image assets and illustrations, video, and other media files, all of which are part of Content Management. But, I’m not going to go into all of that because as I said — it is, like, ridiculously complicated, and the title of this article specifically points out that I will be talking about The High-Level Junk, so I’m gonna. The point is, the management of technical documentation involves an editor (how you make your docs pretty), storage (where your docs live), and output (how you show off your docs). At least it helps me to think of the tools and systems at play in Content Management residing in one of these big buckets. The configuration of these things could look a number of ways depending on where you work and what they got going on, but in general, you’re probably working with an editor and a CMS, or an editor and a repo and a website of some kind.

Right now if you’re like, “This light box sure is throwing some words at me that I do not understand” — Stop. Refer to the earlier paragraph about tenacity. Google is your friend. Or Bing it I guess if you’re feeling feisty and are less interested in getting relevant search results.

Editors — Sometimes Referred to as Authoring Tools

What you use to edit the docs can be anything from Word or Google Docs, to Atom, which is a markdown editor that I use currently, to really clunky stuff that looks like it’s straight out of a Saved By the Bell special (oXygen XML Author I’m looking at you), to really expensive tools like anything Adobe or Madcap. Editors, Authoring Tools, whatever you want to call them, they’re just the face of the thing. They’re not the actual thing. An editor is just the pretty part that you manipulate the text with. And all the text you edit is just a visual representation of 1’s and 0’s. Let that sink in.

Storage Facilities

Y’all. CMSs have gotten BUCK. WILD. Not only are there traditional Content Management Systems like Wordpress or Drupal or Joomla, but there are also Component Content Management Systems (CCMS), Headless Content Management Systems, and Decoupled Content Management Systems. I AM ALREADY TIRED. If you know what any of these things are, or how they work, good for you bb I’m proud of you. I won’t launch into an explanation of each here, but I will link to further reading on each of them at the end of my diatribe. Suffice it to say, CMSs (or repositories) are the part of this landscape where you store the content. Some, like Wordpress are multifaceted in that they’re an editor that is also storage that is also the output. Wordpress was initially built as a blogging platform, so, if you’re doing technical writing on it, I’m sorry honey. :( I would pat you on the head but I feel very strongly about social distancing.

With certain kinds of CMSs (CMS’s? CMSes? CMSssss? Whatever…) like the traditional kind, you have to account for storage, meaning databases, meaning added maintenance and cost. So that, plus the need for developer-driven content in the tech spaces caused the riiiiiiise of the repo, and docs-as-code as a philosophy. GitHub, GitLab, and BitBucket are all just front ends for Git, which is a distributed version control system. You can put your code in there! And now a lot of software companies are choosing to use Git repositories to store plain text files, like markdown, restructured text, and AsciiDoc so it can hang out and look cool next to the code. And since all of the docs are in one place (something known as single-sourcing), you can take all those text files and shove them into something else, like a Static Site Generator (SSG) — which takes me to the next piece.

Output

The general goal of technical documentation is to make something that’s visible to an external audience, unless you’re doing technical documentation for internal teams, which, I’ve been there…. and… I’m sorry honey. :( I would pat you on the head but I feel very strongly about social distancing.

But generally, you want to show what you’ve written to people, so you need something to show, you need output. You also need a way to get the documentation from where it’s stored and pull it into its final form, whatever that may be (usually PDF or an HTML web page). In a traditional CMS, your editing tool, your storage, and your output are all within the same system. Sometimes, however, your output can be a piecemeal configuration of homegrown scripts and websites. Or you might be using a docs-as-code approach like my current company, and employ a static site generator which takes in plain text files and builds all the HTML pages of a website at once.

In conclusion, the content management landscape can look a variety of different ways at different institutions. And the lack of a standard way of doing things drives me insane because I am a technical writer, and I require standards. But, because there is so much to know, and so many different ways of doing this job, the possibilities for both specialization and learning new ways of doing things are endless.

I am a big-time tools nerd, Linux enthusiast (read: NOT GREAT AT IT), and general judgery-doo. If you have any topics you’d like me to cover in a later post — please drop me a comment. Hateful commenters will likely receive a troll cake in the mail.

Have a hashtag blessed day, and happy reading up on my chosen job-hole, you tenacious little honey-badger you. You can do it! I believe in you!

Resources! Yay!

In no particular order, because I believe in sharing information freely and openly, here are some things I’ve found on the interwebs that have informed me, and some of them lawwwwd be still my heart-eyes-cat emoji. Also, if you don’t follow Tom Johnson’s blog I’d Rather Be Writing — what are you even doing, you should be, do it right now. Also join the Write the Docs community because they are the bees knees and I am sad there was no Portland conference this year.

• https://idratherbewriting.com/blog/how-you-write-influences-what-you-write/
• https://doctoolhub.com/
• https://idratherbewriting.com/learnapidoc/pubapis_docs_as_code.html
• https://www.youtube.com/watch?v=Z3e_38WS-2Q
• https://www.writethedocs.org/guide/docs-as-code/
• https://github.com/PharkMillups/beautiful-docs
• https://www.staticgen.com/
• https://www.netlify.com/
• https://rogerdudler.github.io/git-guide/
• https://www.coredna.com/blogs/headless-vs-decoupled-cms
• https://www.smashingmagazine.com/2016/08/using-a-static-site-generator-at-scale-lessons-learned/
• https://www.youtube.com/watch?v=_cuZcnJIjls
• https://jamstack.org/
• https://www.g2.com/categories/component-content-management-systems
• https://www.youtube.com/watch?v=PJcE56UzPVE

Jen Brown currently does technical writing for Redwood Software, and she’s been picking apart what other people say for her entire life. Jen loves those tiny little baby bell cheese things, indoor plant jungles, and paintings that make people uncomfortable. She also has a mild meme collection habit.