Tag Archives: technical writing

“Documentation” is a Dirty Word

Posted on by Leave a comment

I just skimmed through another 20 page planning document, written in old-school “requirements specification”-ese with a hefty dose of ambiguity. You know, things like “the Project Manager shall…” and “the technical team will respond to bugs.”

There’s a lot of good content in there. It’s not easy to get at, though… for each page I want to understand, I can expect to spend between ten minutes and an hour deciphering what’s going on. (That’s half a week of work, and I have a lot of other work to do this week. Is it even worth it?)

Also, this document is boring… and there’s a lot of filler (like “package X is useful, flexible, and open source” – OK, that’s great, and factually correct, but not very informative).

The whole document could have been condensed into 4 or 5 slides of diagrams plus annotations. If that had happened, I’d be looking at a 10 to 30 minute commitment overall to get my brain into this particular company’s context… and then I’d be able to make some useful contributions. (As it stands, I’m weighing whether it’s worth my time to go spelunking in that 20-pager at all. Probably not.)

Unfortunately:

  • The bulk of technical documentation that I read is unintelligible or lacks sufficient meaning. I have three decades of exposure to this stuff, so if I can’t understand it, I feel super sorry for the early career people (who might think they can’t understand it because they don’t know enough).
  • Nearly all of the technical documents I see are uninteresting. And tech is interesting.

99 times out of 100, technical documentation is dull and dysfunctional. While it’s supposed to help people and teams establish a shared understanding of a system or a process or a concept, it just ends up looking really impressive and convincing you that the authors know a lot more about this than you do. It doesn’t help you much, if at all.

And as a CTO, CIO, or VP of Engineering, I don’t want to pay for crappy documentation. This particular document probably cost me between $32K-50K, and that’s just the tip of the iceberg… because it doesn’t account for the incremental costs of the people who will attempt to decipher it – which could be 10-100x more over the lifetime of that document. Although the person or team that wrote the 20-pager probably knows what’s going on (at least a little bit), the artifact itself is going to cost other people time and take them away from more value-adding tasks.

The sheer volume of information we’re required to wade through to gain understanding – without the assurance that it will lead us in the right direction, or even in any direction at all – is probably what’s led to the disease of devaluing documentation. 

A lot of managers think documentation isn’t value-adding, and shouldn’t be done, because… in most cases, people do it so badly that it wasn’t worth the investment in the first place.

Dear tech workers: can we fix this, please? I know it will take a whole generation to effect meaningful change, but… I’m ready to roll up my sleeves.

Improve Writing Quality with Speaking & Storyboarding

Posted on by One comment

For a decade, I supervised undergrads and grad students as they were completing writing projects: term papers, semester projects, and of course — capstone projects and thesis work. Today, I’m responsible for editing the work of (and mentoring) junior colleagues. The main lesson I’ve learned over this time is: writing is really hard for most people. So I’m here to help you.

Me, Reviewing Someone Else’s Work

If I had a dollar for every time this scenario happened, I’d… well, you get my point:

ME (reading their “final draft”): [Voice in Head] Huh? Wow, that sentence is long. OK, start it again. I don’t understand what they’re saying. What are they trying to say? This doesn’t make any sense. It could mean… no, that’s not it. Maybe they mean… nope, that can’t be it.

ME: So this sentence here, the one that says “Start by commutating and telling the story of what the purpose of the company’s quality management software is, the implementation plans and the impact to the current state of quality roles and responsibilities for everyone involved.”

THEM (laughing): Oh! Commutating isn’t a word. I meant communicating.

ME: Have you tried reading this sentence out loud?

THEM (still laughing, trying to read it): Yeah, that doesn’t really make sense.

ME: What were you trying to say?

THEM: I was trying to say “Start by explaining how quality management software will impact everyone’s roles and responsibilities.”

ME: Well, why don’t you say that?

THEM: You mean I can just say that? Don’t I need to make it sound good?

ME: You did just make it sound good when you said what you were trying to say.

What Just Happened?

By trying to “make it sound good” — it’s more likely that you’ll mess it up. People think speaking and writing are two different practices, but when you write, it’s really important that when you speak it out loud, it sounds like you’re a human talking to another human. If you wouldn’t say what you wrote to someone in your target audience in exactly the way that you wrote it, then you need to revise it to something you would say.

Why? Because people read text using the voice in their heads. It’s a speaking voice! So give it good, easy, flowing sentences to speak to itself with.

What Can You Do?

Here are two ways you can start improving your writing today:

  1. Read your writing out loud (preferably to someone else who’s not familiar with your topic, or a collaborator). If it doesn’t sound right, it’s not right.
  2. Use a storyboard. (What does that mean?)

There are many storyboard templates available online, but the storyboard attached to this post is geared towards developing the skills needed for technical writing. (That is, writing where it’s important to support your statements with citations that can be validated.) Not only does citing sources add credibility, but it also gives your reader more material to read if they want to go deeper.

Storyboarding

The process is simple: start by outlining your main message. That means:

  1. Figure out meaningful section headers that are meaningful on their own.
  2. Within each section, write a complete phrase or sentence to describe the main point of each paragraph or small group of paragraphs
  3. For each phrase or sentence that forms your story, cut and paste material from your references that supports your point, and list the citation (I prefer APA style) so you don’t forget it.
  4. Read the list of section headers and main points out loud. If this story, spoken, hangs together and is logical and complete — there’s a good chance your fully written story will as well.

Not all elements of your story need citations, but many of them will.

Next Steps

When the storyboard is complete, what should you do next? Sometimes, I hand it to a collaborator to flesh it out. Other times, I’ll put it aside for a few days or weeks, and then pick it up later when my mind is fresh. Whatever approach you use, this will help you organize your thoughts and citations, and help you form a story line that’s complete and understandable. Hope this helps get you started!

STORYBOARD (BLANK)

STORYBOARD (PARTIALLY FILLED IN)