Archive for the ‘Commentary’ Category


WebWorks RoundUp 2009

October 21, 2009

I’m just returning from WebWorks RoundUp 2009. It was a road trip (I drove to Austin from Colorado), my first solo road trip in years, and so far it has been a blast.

First of all, thanks to WebWorks for providing copies of two XML Press books to attendees. All attendees got complimentary copies of my Managing Writers and Anne Gentle’s Conversation and Community, and XML Press gave away a copy of Alan Porter’s forthcoming book, WIKI: Grow Your Own for Fun and Profit.

I thought the conference was a model of the kind of conference a company should have for customers. While the conference is open to all, it is primarily focused on WebWorks customers, who are an interesting, enthusiastic group of people, who are not shy about expressing their opinions.

I was equally impressed with the management team; the top managers were there throughout, accessible to the audience, and participated in most of the sessions, as moderators and participants. They got some honest (i.e., tough) comments from the audience, and handled them well. That said, the positive out-weighed the negatives by a mile.

The conference was divided into two tracks. The first was a “Boot Camp,” which matched up customers with technical experts, with a loose focus (things like Automation and DITA) that as far as I could tell served mostly as ideas for discussion. The second was a more traditional panel-focused set of sessions, with some case studies. This is where I spent most of my time.

Stewart Mader, author of Wikipatterns, gave the opening talk and joined the first panel, which centered on wikis and social media. His talk and the panel set a direction to the conference around wikis and using wikis as part of documentation. He brought up, though no one really answered, the question of whether you can use a wiki as your complete documentation set. I suspect it will work with some, but not all, products.

XML Press authors Anne Gentle, Alan Porter, and I were all there, and we all participated in panels (not all together, unfortunately; that would have been interesting). Anne spoke about her book, Conversation and Community, and also joined a panel on DITA with Lisa Dyer and Georg Eck. Alan participated on several panels, including one that I also joined about content development best practice, which refreshingly concentrated on what goes between the tags, rather than the tags (the idea of concentrating on what goes on between the tags was from Bob Sima of Tedopres).

Tom Johnson, author of the I’d Rather Be Writing blog (a must read) gave the keynote for the second day, talking about the “Seven Deadly Sins of Blogging,” which has been the topic of several good, recent blog entries on his blog.

Overall, I found the conference interesting and entertaining. I also found my first real visit to Texas since living there in the late ’70s to be a lot of fun. I’d forgotten a lot about Texas. Here are a few tidbits:

  • First barbecue place I passed headed south on I35 had the following billboard (approximately, though the name of the piece de resistance is literal):

    Big Fatty’s Barbecue, home of
    El Farto Grande

  • Sign in the men’s room of two different places, including the conference hotel, warning you to not drink alcohol if you think you might be pregnant. Reliable sources tell me that the women’s room in the hotel did not have that sign
  • Under the category of “2nd Amendment anomalies,” I visited friends in a new housing development in Texas that featured a prominent “No Firearms Allowed” sign at the entrance to the development. Clearly an enclave of Damn Yankees (I learned when I lived in Texas that there is no such thing as a Yankee; you’re either a Damn Yankee, or you’re ok).
  • My favorite definition of the conference, courtesy of Mary Anthony, who gave a very interesting talk the first day. She defined agile methodologies as “Developers gone wild.”

Health Care, the Stock Market, and Jeopardy

October 9, 2009

Final Jeopardy:

Answer: Proof positive that Congress has come up with a health care bill that works for the people.

Read the rest of this entry ?


SXSW Panel Discoveries

August 31, 2009

I just spent an hour browsing through the SXSW 2010 Panel Picker voting site. If you haven’t seen this, it’s worth a look. The SXSW program team posts descriptions of proposed panels for the conference (where panel can also be a presentation). Anyone can view the proposals, but the cool part is that you can vote thumbs up or down on any proposal (to vote you need to register, but it’s free and fast).

I went over to the site because XML Press author Alan Porter has two panel proposals, Wikis are Wonderful – or Are They? and Spandex and Software: Can Comics Get You To Read The Manuals?. Both look very interesting and well worth voting for. Alan always has something interesting to say, and you can bet he will show some good comics as part of his panels.

In addition to Alan’s panels, which I urge you to check out and vote for, I was really pleased to see proposals by several other people whose work I respect, including:

Greening Your Content: Reduce, Reuse, Recycle by Rahel Bailie

Coauthoring Without Homicide by John Hedtke

All About Audience: Improving User Experience by Brenda Huettner.

Will User-Generated Content Wipe Out Technical Writers? by Sarah O’Keefe.

I was also pleased to see several panels on publishing, which curiously does not have its own category, but which is represented in categories like Writing. In addition to reading about, and voting on, several publishing related panels, I followed links to some interesting sites, including a blog by Richard Nash that’s now in “tight rotation” on my list of daily reads.

On a completely different note, after watching Julie/Julia yesterday, I started reading the original Julie/Julia Project blog, which is fascinating. I started with the first entry and am working my way through in the order it was written. Well worth checking out. I’m reading it in parallel with Julia Child’s My Life in France. I haven’t seen Julie Powell’s Julie and Julia: My Year of Cooking Dangerously, yet, though if the blog and Julia don’t wear me out on butter-based food, I may give it a try, too.


Seize the Moment

August 26, 2009

We just got back into town after a short trip. When we left, our grape vines still bore green, unripe grapes, and we thought they would ripen after we returned. Because of that, and frankly because it’s a real pain, we didn’t put netting over the vines like we usually do.

We came back to a scene of mass bird destruction. The vines were completely stripped of grapes, and the surrounding deck and patio were covered with the inevitable “output” of well-fed birds. The result of inaction is that our crop of grapes is gone for this year, and we have an unpleasant clean-up ahead of us. Fortunately for us, we don’t depend on grapes for our livelihood, but the event brought home to me the importance of acting decisively when opportunity beckons.

As managers, we often look at the consequences of our actions, but I think we often ignore, or are completely oblivious to, the consequences of inaction. We get absorbed in the day-to-day business of being a manager, react to whatever comes our way, and leave opportunities unexplored. This is always dangerous, but with the massive changes going on in the technical communication world, the cost of watching from the sidelines can be your job.

Having just published Anne Gentle’s Conversation and Community: The Social Web for Documentation, I’m acutely aware of the opportunity Social Media provides for technical communicators, but even more aware of the danger of ignoring Social Media.

No one knows whether twitter, facebook, linkedin, etc., will be around in 5 years, or 5 months, but you can bet that Social Media in some form or another is here to stay. Even if you aren’t using Social Media, your customers are. They will learn about your company from others who use Social Media, and they will notice how you use, abuse, or ignore those venues.

The good news is that as Social Media evolves from its current immature beginnings, there is room for experimentation and there is an opportunity to be at the front of this trend. But, very quickly, the question will change from “How should I be using Social Media?” to “Why aren’t you using Social Media?” If you’re not acting now, you may soon discover that the grapes have been eaten and all you’re left with is bird droppings.


DocTrain RIP

May 18, 2009

I was sad to get the news this morning of the demise of the DocTrain conferences. I’ve been to DocTrain West twice and was privileged to be able to present at this year’s conference. And, I was getting prepared to present two sessions at DocTrain/DITA, both on DocBook. Scott Abel, who was contracted by PUBSNET to market and run DocTrain, agreed with me that some sessions on DocBook would be a nice counterpoint to the incessant DITA drumbeat. I was especially looking forward to some spirited give and take on DITA and DocBook.

Scott’s involvement is the thing that distinguished DocTrain in my mind. He is an indefatigable organizer who kept the programs lively and attracted a broad base of presenters and attendees. Whenever someone posted the inevitable, perennial question, “which conference should I go to,” on a mailing list or news group, the inevitable, perennial reply was “go to DocTrain if you want substance and interaction.”

That was in no small part due to Scott. While the demise of DocTrain is bad news, the good news is that Scott is continuing to look for ways to connect people (Scott is a connector in the best Malcolm Gladwell sense; Gladwell detractors be damned, I think he’s spot on about connectors). You can be sure there will be new events, virtual and in-person, and I plan to be there.


When Number One Isn’t Enough

April 18, 2009

Like many people, I periodically drop various key words and phrases into Google to see how well my sites (this one, plus and fare. If you run a business, the “vanity search” is no longer a question of vanity; you need to be near the top of the first page of results for keywords that matter to you and your business.

To that end, I dropped “technical documentation” into Google, and was a little surprised to see that the first hit was, a site I know well because at one time I managed writers who contributed content to it. Probing a bit deeper, I found that it also comes up first if you search for “HP documentation.”

Good job, Hewlett-Packard…. But, wait a minute. At the top of the page, there is a note, in red, that reads, “Documentation moving March 2009.” Following the link, here is what I found:

In March 2009 the documents on this website will begin to move to the HP Business Support Center (BSC) website. The move will be gradual and conducted in stages. During the move, you can expect uninterrupted access to documentation. After a group of documents moves, you will be redirected to the new location on the BSC. Use the Feedback to webmaster link below to submit any questions.

Click here for more information about the BSC. At the bottom of the BSC info page, click Visit the HP Business Support Center. On the Business Support Center page under Resources, click Manuals.

So, being a dogged fellow, I followed the link for Manuals and landed on a page with a potpourri of product categories and a search box. When I searched for hp-ux (that’s HP’s Unix operating system), I ended up on a page that contains links to a somewhat random collection of PDF files. In fairness, this is a work in progress, but two things disturbed me:

  1. Why abandon a sub-domain ( that gets superb positioning in Google? Companies pay big money to get good placement on Google (and often fail in the effort).
  2. Why abandon HTML as a format? In fairness, maybe HTML will be part of the new solution, but so far, I see nothing but PDF on the new web site. has never been a perfect site, in particular, it never fully cracked the very difficult problem of making it easy to navigate very large documentation sets, but it is very popular (Google doesn’t lie) and offers a wide range of documentation in HTML and PDF form.

Burying it makes no sense (and I mean really burying it; the site (memorably named where this information is going doesn’t show up on the first six pages of a search for “HP documentation”; I gave up after that). And, even with the smaller number of documents currently on the site, it is clear that they are no closer to cracking the very large documentation set problem. Abandoning HTML documents, if that is what happens, will just make things worse; PDF is great for print, not so good for online.

I’m no longer at HP, but I’m still disappointed that this is happening; I hope HP gets its act together and preserves both and documentation in HTML (and it wouldn’t hurt if they took a serious swipe at the very large documentation set problem).


Article: Reuse Considered Harmful

November 7, 2008

The Content Wrangler published another of my articles, which can be read at the following URL: Content Reuse: Is It Harmful?

I originally titled the article, Reuse Considered Harmful in honor of the famous letter by Edsger Dijkstra published in the Communications of the ACM, Go To Statement Considered Harmful. Though the term XYZ Considered Harmful is forever attached to Dijkstra, he in fact did not use that title, it was added by Niklaus Wirth, then editor of the Communications. So, I suppose it is only appropriate that the editors of The Content Wrangler renamed my article Content Reuse: Is It Harmful?

My main argument is that we should be careful about indiscriminate reuse of content. Eliminating duplication in your source control is fine, but blindly reusing content all over the place can be confusing to readers who may end up jumping around looking for the definitive version of some piece of content. I believe it is much better to follow the timeless advice of Isabella Mary Beeton, “a place for everything and everything in its place.”