Posts Tagged ‘technical writing’


STC Summit 2010

May 7, 2010

I just returned from the Society for Technical Communication (STC) Summit in Dallas, TX. The conference this year had a much more optimistic feel than the last couple of years. This year, I actually met more people looking to hire than looking to be hired, which was not the case at the last two conferences. Of course, given that those looking for jobs often don’t have the means to travel to a conference, I wouldn’t argue this is conclusive evidence of an upturn, but it was encouraging.

As has been the case with nearly every conference I’ve ever attended, the greatest value came from interactions outside the sessions (of course, the sessions are essential, they provide a framework both in terms of the schedule and the topics of discussion, but they are just the starting point). What struck me most from both the sessions and the informal discussion is that the technical communication community is fully embracing the technologies and methodologies that have been bubbling around for the last few years. In particular, XML (esp. DITA) and social media are mainstream. The questions and discussions centered around how best to use these tools, not whether to use them.

I had the opportunity to visit with nearly all of the XML Press authors (Robert Delwood, Anne Gentle, Brenda Huettner, Alan Porter, and Zarella Rendon), plus meet a few prospective authors.

I also had the opportunity to do the following video podcast with Tom Johnson about XML Press and our current offerings. For more information about these books and other offerings, go to One note, the video was done on the spur of the moment with no chance for me to prepare, and I forgot to mention our newest author, Robert Delwood, whose book, tentatively titled “The Secret Life of Word” looks at how technical communicators can get the most from Microsoft Word (Sorry, Robert).


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).



April 16, 2009

I’ll be headed to Indianapolis for the DocTrain/DITA conference (June 2-5) to talk about DocBook, of all things. More on that in a moment, but first a quick plug for the conference itself.

If you have been to any of the DocTrain conferences, you know they combine in depth pre- and post-conference workshops with excellent keynotes, demonstrations, and talks. I like the flexible format; talks and workshops range from an hour to all day, depending on the topic, so you can get a taste or full immersion in the topics of your choice. This one is devoted 95% to DITA (my DocBook presentations are the only exceptions I’m aware of).

Until April 30th, the organizers are offering a great hotel+conference offer that includes the full conference, workshops, several meals, and three nights hotel for $999. Details here, or call Eileen Savary at +1 978-649-8555 and use discount code “Conference Plus Hotel.”

I’ll be doing two sessions, the first titled: DocBook in the 21st Century: Yes, Virginia, There is a DocBook, and it is Alive and Well, which has the following blurb in the program:

The latest release of DocBook, V5.0, is a significant break with earlier releases. While the differences between DocBook V4.x and V5.0 are quite radical in some aspects, the basic ideas behind DocBook remain the same, so moving from earlier versions to V5.0 is straightforward.

DocBook V5.0 includes new markup for annotations, a unified markup for information sections, and a new and flexible system for linking. In addition, V5.0 is more extensible; it can be more easily modified, and it can be extended in separate namespaces to allow you to easily mix DocBook markup with SVG, MathML, XHTML, and other XML-based languages.

This talk will start with a quick orientation to DocBook for those who have not seen it before, then look in depth at V5.0.

I’ll also be doing a workshop titled Getting Started with DocBook, which is designed to do just that. Here is the blurb:

This workshop will get you up and running with DocBook. If you bring your laptop with you, by the end of the session you should be able to create and publish a DocBook document in html and pdf output formats. The workshop will include basic information about the DocBook schema, DocBook stylesheets, supporting software, and how to put it all together.

If you’ve wondered what DocBook is all about, if you are evaluating it alongside other schemas, or if you want to use DocBook for a new project, this workshop will get you started.

I’ll be interested to see how much, if any, interest there is in DocBook at a DITA conference. I’m cautiously optimistic that there will be enough curious folks to fill the room; we’ll see.

In one last moment of shameless promotion, there will be copies of Managing Writers for sale at the conference.


Podcast Interview about Managing Writers

March 24, 2009

Tom Johnson just posted a podcast of an interview with me at his website,

In the interview I talk about Managing Writers and answer Tom’s questions about the book.

Most of the discussion was about managing people, including questions about hiring, evaluating writing samples, motivation, planning, and lots more. If you are interested in the book, the interview is a good way to get more information about its content and about my approach to management.

Thanks, Tom, for taking the time to read the book (and it is clear from the interview that he did read the book in detail), and to speak with me about it.


What Doc Managers Look for in a Résumé

March 4, 2009

Lately, a lot of technical communicators have found themselves updating their résumé for the first time in a long time. This prompted someone on the Techwr-l mailing list to ask hiring managers in the group what they look for in a résumé.

There are plenty of sources for information about how to write a résumé, but less on what doc managers are looking for. My book, Managing Writers: A Real World Guide to Managing Technical Documentation, contains a chapter that discusses hiring in detail. I have included an excerpt below that discusses how I evaluate a résumé.  I hope you find it useful.

Read the rest of this entry ?