Archive for February, 2007

h1

New Section: Motivation

February 27, 2007

I just posted a new section on motivation. It’s a bit longer than some, but motivation’s a juicy topic. As usual, I encourage you to comment.

Thanks are due to Larry Rowland, who introduced me to the quote that heads the section.

Here’s a pointer to the new section: Motivation

Advertisements
h1

Models

February 23, 2007

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.

h1

New Section: Human Resources

February 15, 2007

I just posted a new draft section titled, “Everything you wanted to know about HR, but were afraid to ask.”

I don’t know if I’ll stick with the cutesy titles, in fact I’d appreciate input on whether they’re ok or not, but for now I’ll leave this one as is.

Generally, I like the overall feel of this section, but I think there’s more that could be added. If anyone has suggestions for HR related topics that I should cover, please leave a note. And as usual, I’d like to get your input.

Here is a link:Everything you wanted to know about HR, but were afraid to ask

h1

New Section: Power of the Pen

February 12, 2007

I just posted a new section for review. A major theme of this book is power and influence. This section talks about formal and informal authority and gives an example that some of you may recognize. Here’s a link:

The Power of the Pen

h1

Getting Updates

February 8, 2007

I got a question asking how to use RSS to receive a notification when new information is posted on the blog. It turns out there are a boatload of ways to do that. I’ve added links to handle a few of them in the “Feeds” section at the bottom of the right hand column. Here’s a quick description:

  1. RSS Feed: If your browser supports RSS, just click on the RSS Feed link and you’ll be in business. Some browsers also automatically detect feeds and let you sign up (look for this icon in the browser’s toolbar: ).
  2. My Yahoo or Google: If you have a personalized My Yahoo or Google page, there are links for each.
  3. Other aggregators: You can directly use the feed link, (https://rlhamilton.wordpress.com/feed) in a feed aggregator like Bloglines.
  4. FeedBurner: If you’re using a pure RSS feed, the RSS link is the best way to go, but if you prefer FeedBurner for some reason, I have the following RSS feed there:
    http://feeds.feedburner.com/ManagingTechnicalDocumentation.
  5. Technorati: If you use Technorati, there’s a link to add this blog to your Technorati favorites.
  6. Email Updates: If you’d like email updates, there’s a link that will bring up a form for you to enter your email address to get an automatic update when something is posted (you should get no more than one update/day, and then only on days when there’s a change).

I hope that helps; if you have any trouble subscribing for updates, post a comment or send me email.

h1

Wiki for docs

February 7, 2007

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.

h1

Ramping Up

February 5, 2007

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.