Everyone who uses tools for a living loves their tools. And has strong opinions about them. Most programmers are happy to talk about their favorite coding languages and development tools, for example. For tech writers, we get to argue about content management systems, authoring tools, authoring formats, documentation structure…And that’s after we’ve battled over grammar, font choice, and glossary terms. Seriously: Glossary battles are the worst.
Now I find myself needing to change my writing process, and probably adding a tool or two to my workflow. Oh joy.
What I’m doing now
This is where some of you are going to wail, moan, and gnash your teeth in horror, scorn, and general “I can’t believe he’s doing it so wrong”-ness. My process is:
- Go to my knowledge center.
- Open an existing topic, or add a new one.
- Type. Right there, in the editor. It’s a WYSIWYG editor, even.
- Import images, add links, make sure the headings make sense.
Horrific, I know. But it’s also fast, easy, and means that the process is very, very fast.
To be perfectly honest, I create new topics in a hidden Draft folder, and then ask the appropriate SME to review the content. And based on Tom Johnson’s suggestion, I’ve been changing my process of writing longer topics to do the writing in Google Docs, and have the reviewers check it there before I move it to the knowledge center.
But for small topics or minor edits, that list encompasses my writing and publishing process.
And it’s wonderful
I don’t have to validate the structure of the docs against any structural constraints other than my own. I don’t have to pass it through a formal word choice list, or any other draconian measures routinely imposed by standards groups on poor, suffering writers.
Obviously, this is possible because of two reasons:
- I’m in charge of the documentation.
- I’m the only writer.
I hold the standards within my own head (“try to write stuff that’s useful and makes sense”), so there’s the obvious problem of scaling this solution to more than one writer. In the past, I’ve done this by hiring really competent writers; while I don’t plan to change that part of the process, I also want to minimize the amount of work they have to do to get up to speed.
Here’s why that won’t work
Or “here’s why that won’t work well”: It works when I’m documenting a single product. Or if I document multiple products that don’t share content. But it doesn’t scale well if I have to document multiple products that do share content. In that case, I’ll need to do a lot of cutting and pasting. I’ve done that before, enough that I don’t trust myself to do it too often.
On the other hand, my requirements aren’t too complex.
And here’s what would work
I need some tool that’s inexpensive to purchase, install, configure, and maintain. “Inexpensive” in terms of money and time, since I don’t have a large budget of either. Fortunately, I just need to output to HTML. PDF output would be nice just in case anyone asks, but it’s not a requirement.
My existing content can be exported to HTML. I’m not stuck with any proprietary formats, or even something common-yet-messy, like Word.
So I need something that allows for content reuse, and tracks and manages those pieces of content, and makes sure that those pieces are in sync with each other.
I’d love something that would let me set up a structure, write, export to that structure, and then would keep everything under control, even when I decide that the original structure is stupid and need to rebuild it three days later.
And a big nice-to-have
Support for collaborative authoring. Which requires a non-arcane syntax, because even a small barrier to entry is enough to keep the potential authors away.
Basically, anything more complex than markdown isn’t going to work. When you’re asking someone to do you a favor by helping you create documentation, they won’t be eager to learn a documentation syntax that they’ll use once a month, at most.
And, yes, I realize that they’re doing your company a favor by documenting the information that’s otherwise stuck in their heads, but most people are going to look at their schedules and consider this just one more request on an already too-long list.
So I’ve put together a list of requests. Now I need to figure out what tools are out there (I know that the answer is “a lot”), and match them to that list.
I’m just a little afraid that I’m asking for a unicorn, and the answer will be “Sounds great; feel like coding it yourself?”