Plain Text and the Technical Communicator
Writing software documentation has been my day job for the last 25 or so years. During that time in the trenches, a lot has changed in the profession — tools, techniques, philosophies, approaches.
Over the last few years, the concept of Docs Like Code has been … well, it hasn’t been sweeping the technical communication world. It has, though, become increasingly popular with writers preparing technical documentation for developers, DevOps, and the like.
I’m not going to go into the details of Docs Like Code here. If you want to learn more about Docs Like Code, you can’t find two better teachers than Anne Gentle and Tom Johnson
But what does this have to do with plain text? A lot. Using the Docs Like Code approach, you write documentation in plain text, formatting it with a markup language like Markdown or ReStructuredText. Then you publish it on the web using, for example, a static site generator like Jekyll.
Taking that path makes a lot of sense, for a number of reasons. You don’t need expensive help authoring software. You’re using a format that’s not going to change. And you get to embrace your inner geek a bit.
That said, there will always be groups of technical writers who refuse to move away from the well-known, so-called standard tools of the profession. It can be difficult, if not impossible, to convince them to switch to a Docs Like Code workflow. Yes, I am speaking from experience — I’ve broached that subject at various Day JobTMs over the last few years and barely escaped from those meetings with my head still attached to my neck.
So what’s a plain text-loving technical writer to do? Sneak as much plain text into your workflow as you can.
Let’s take a look at a few of the ways in which I do it, which also might work for you.
Planning and Task Management
At the start of a new project, I always map out what I’ll need to write about based on the list of features and enhancements for that project. Once development gets underway, I create outlines based on the outcome of investigating what needs to be done and what actually will be done.
Each week, I create a plain text task list for the work I need to complete. Depending on the week, that list can be quite fluid as new priorities crop up. A text file is, as you know, easy to edit and maintain. It’s perfect for a fluid situation.
For both, all you need are a text editor and a folder structure to organize those files. Nothing complex, nothing fancy. Just tools that are already on your work computer.
Notes
That’s a given, isn’t it? When I’m working through a feature, doing research, or talking with a subject matter expert, I take notes in a paper notebook. Once that’s done, I type those notes up in a text editor.
It’s not just straight transcription of the notes. I also fill in information that I remember but wasn’t able to jot down. On top of that, I add placeholders for questions and where I need more information.
Drafts of Release Notes
In late 2018, I introduced a Docs Like Code-inspired workflow for writing and reviewing release notes to one of the teams I work with at The Day JobTM. I write drafts of the notes in a text editor, formatting them with Markdown. When it comes time for a review, my reviewers make a copy of the file in a GitHub repository where I store the notes and add their comments or changes.
When they’re done, I go over those comments and changes and then merge them into the master copy of the notes. That sounds techie, but understand that I only know enough about GitHub to do what I need to do. Or to get into trouble.
Taking this approach is better than trying to keep track of multiple word processor documents or deal with several peoples’ revisions in a single document. Using text files and GitHub actually removes a lot of friction from the process.
The only time I break from this workflow is when the product manager, who’s not interested in using GitHub, has to review the release notes. I convert the draft to a word processor format for the product manager. That only takes a few seconds, and everyone is happy.
Writing Drafts of Help Topics
Although I use something similar to a Docs Like Code workflow for the release notes, I have to use a frequently-frustrating proprietary tool for creating online help. When I write help, I break it into smaller, focused topics. But instead of using the company’s preferred application to write drafts, I write them in a text editor.
As you’ve probably guessed, those drafts are formatted with Markdown. When I’ve finished the drafts and they’ve gone through a review, I convert them to HTML using Pandoc and then drop them into the that tool I mentioned.
Final Thoughts
What I’ve just described isn’t the only way to introduce plain text into your technical writing workflow, especially when your colleagues are resistant to switching to Docs Like Code. For me, this has been the most flexible way to sneak plain text into the office while staying productive.