On the Virtue of Asking Questions

If you have been staring at a spec page for an hour or more, trying to make sense of it, you should send an email list of questions to the software developer who wrote it. Doing so all but guarantees an epiphany five minutes later, ensuring the maximum amount of feeling like an idiot for wasting his or her time.

A Wee Bit of Math

I did some adding up this morning and determined that I am personally responsible for maintaining just under 1,000 pages of product documentation. That doesn't include two rebranded documents where I don't own the content, or a programming guide to which I make occasional contributions, but does include eight active product documents. No wonder I sometimes feel dizzy....

A Human Factors Observation

People want to be precise, even if the situation does not call for it (even, in fact, if being precise works against the goal); give people a range that includes three options, and they will try to add more. I've seen this happen most with hiring, where people apparently cannot stick to yes/no/neutral assessment of a candidate, but must add "yes, but..." and "no, sorta..." options.

I've also now seen it with scoping. When we make our first pass at how long a project will take, we assign small/medium/large effort estimates to each task--or at least we did. I see that we have now added "extra-large" to the list of estimate options.

I'm not at all sure what this says about people, but I find it fascinating.

Nothing Personal

I spent all day Wednesday in a session with our support team and one of the developers, taking notes as they followed the installation guide I wrote to try to install one of our more problematic products. By the end of it, I had two pages of notes, a lot of questions that need to be answered, and can't say I was feeling any too good about the job I'd done.

One of the hardest parts of writing comes in taking criticism. What we write is extremely personal, whether it's a letter, a novel, or an installation guide; it comes directly from our minds into its final form, without mediation. So it is difficult, when the criticism comes in, not to feel ourselves attacked, to get defensive, to offer up excuses for why information is missing, or hard to find, or just plain wrong.

Difficult, but vital. It's one of the more annoying universal truths that the easy way is almost always wrong. No piece of writing is perfect in its first draft, and sometimes we're too close to see the problems. Taking feedback and making the necessary judgments--is this really a problem? will the suggested change help? or is this person off their rocker? is part of the craft.* Ignoring feedback cuts us off from one of the main ways we can improve our writing, and encourages writing from habit rather than thought. If I can't answer the question, "Why did you do that/do it that way?" I am not writing well.

The upshot of yesterday's exercise is that I didn't do the best job I could have done with the documentation. Having given myself a few minutes to sulk about how it's not my fault, it is now time to fix it. In a few weeks I'm going to sit down with this team again, and we'll do the whole test again, and see if it's better.

*I am in the "tech writing is craft, not art" camp, in case anyone cares. Perhaps I'll post more on that subject at some point.

Scrum, Scrum, Scrum

Not only is it fun to say*, it's a development methodology. We are giving it a try on one of our projects, and I am the writer on that project, so I hope I will have many thoughts on how it all works. To get started, some basics.

Excellent and Consistent Content Development through Agile and Scrum

Wikipedia on Scrum

* I suspect that a lot of the terminology in agile stuff was thought up late at night.

Component Publisher

As I continue to contemplate a major cross-product documentation project (while sitting in a meeting that looks like it will never start because 4 of 6 required attendees aren't here), I keep coming back to the thought that there must be a way to do this. Last week's research grabbed a tool called Component Publisher, by an Israeli company called Live Linx. It sounds great - MS Word-based document bits that can be sewn together as needed - but I haven't found a single product review online, which makes me nervous. Tech writing tools don't usually get a lot of press, but there should be something.