Managing Writers

Over the last week I’ve been working on two new sections, one on motivation and one on planning. The first is nearly ready, but is still giving me heartburn, and the second needs a lot of work.

This note is to let you all know that I haven’t disappeared, I’m just not comfortable posting what I have ready today. You can expect a new section in the next few days.

In an unrelated vein, I had an interesting email conversation with a friend and former colleague who asked me if I had an overall vision for the kind of book this would be (beyond what the title implies). He went on to suggest that I consider what kinds of books might be good models. Here’s a piece of my reply to him. I’d be interested in any thoughts on it:

Until you mentioned it, I hadn’t thought very much about models. After thinking about it for a while yesterday, I think one interesting model would be “The Elements of Style,” by Strunk and White, even though it’s nothing like what I’ve written so far. S&W is short, contains a lot of information, and holds up to regular re-reading. Kernighan and Plauger’s “Elements of Programming Style,” itself an homage to S&W, is another example I like. An example in a different style is Malcolm Gladwell’s “The Tipping Point,” which makes many of its points through stories.

When I started writing this, I had a long conversation with a friend who teaches at at CSU (Colorado State U). He ran a study where they tried to see how effective stories were in teaching.

They got a top expert in the Quick Sort algorithm to videotape a lecture describing the Quick Sort. Then, using the same slide set, they videotaped someone using a story about a princess who wants to sort her belongings to describe the algorithm. They found that students who learned the algorithm from the story did better in a post-test than the group that got it straight from the expert.

When I told him about this project, his suggestion was to use stories extensively, both for the ultimate audience and for the audience of folks reading this as I write it. He thought that stories would draw people in and keep them coming back for more each week.

Now, while I don’t plan to make up stories about princesses, I do want to make the book interesting, so I’ve taken his suggestion at least in part and am using stories where they make sense.

That’s it for now. As always, comments are welcome. Have a great weekend.

I received email from a few folks suggesting I look into the use of Wikis for technical documentation. Does anyone have direct experience doing this, and if so, how did it go?

I find the idea intriguing. Clearly, wikis have been a great success with reference material, like Wikipedia, and I’ve found some to be very useful, for example the DocBook WIKI. I particularly like the idea of using a Wiki for fast moving, customer driven information. For example, a Wiki FAQ could be a great substitute for, or supplement to, support forums, which are not one of my favorite forms (there’s just too much junk, too little structure, and too little moderation in most forums). This is already popular for general topics (check out wikifaq.com for one interesting general purpose FAQ in Wiki form), and I’ve seen it used for open-source software. Does anyone know of an example for commercial software or other products?

Using a Wiki for commercial products poses a different challenge, since there is an expectation, in fact a legal obligation, that documentation will be accurate (or at least that you will exercise due diligence to make it as accurate as possible). Opening up your documentation to any yahoo to update doesn’t strike me as exercising due diligence. So, I expect that to use a Wiki, you will need to be very careful and clear about where you open up access and where you don’t.

However, I think there could be a powerful hybrid between traditional documentation and Wiki-style documentation. How about having a base of docs that is locked down (or at least moderated) for outside access, but open for free access to the technical documentation team, plus an open Wiki area, including a FAQ, that anyone, or to be conservative, registered users, can update? The technology wouldn’t be a problem; all the pieces are easily available and could be put together with little difficulty.

The biggest challenges would be moderation, including the ability to respond quickly to wiki-spam and other anti-social activities, and (maybe bigger) getting management acceptance for the idea that the documentation can be changed instantly by any technical writer (it wouldn’t surprise me to find that many would have a harder time giving that power to their writers than to their customers).

On that happy note, I’ll leave the question open. Feel free to post a comment with your thoughts.

If you’re looking at this in response to an email from me, thanks for taking the time to check this out. If you just stumbled on this some other way, welcome too.

Starting this week, I will be adding content to the book at least once a week. I’ll also be updating previous sections as I receive comments. Feel free to comment using the comment section at the end of each post. If you want to send a private comment, just say so at the top and I won’t post it.

If you’re just getting started, I suggest reading the following two pages first:
About this blog
Note to Participants

Then, dive right into the first section, Becoming a Manager, or if you prefer, check out the Outline.

Either way, I hope you enjoy following along and find it worth your time.