Monthly Archives: January 2006


Product documentation can make a difference

In reading this article that compares Solaris to Linux, something caught my eye about the product documentation

Yes, the quality of the documentation will be noticed when it stands above the crowd, and people will compare technical docs product to product. This article titled Solaris Review: Solaris Welcome Home! by Brandon Werner that I found on James Governor’s list has a great section talking about mature documentation (and even hints at the inadequacy of wiki for technical documentation, although I won’t interpret beyond what he might have intended). Here’s an excerpt from the relevant section. A good read.

Solaris 10: Documentation without the O’Reilly Tax.

What really separates Solaris 10 from the pack is the documentation. If you don’t think you’ll take advantage of documentation, it’s only because you grew up without it on Linux, and Google has been your only recourse. Solaris did not grow up in the world of HTML HOW-TOs and Wikis. Far from it, there is enough documentation online to kill a rainforest if printed. And it’s really good documentation too; documents that walk you through everything you’d ever want to do from setting up Sendmail to using NIS+ to configuring network services. It has high-level overviews with detailed walk-throughs and advances at the level of the reader by providing quick methods to get started and then drilling down in to the details as people get more comfortable with the services they are deploying.

An interesting side note — Brandon’s in the Cinci area, where I went to grad school and completed my first tech writing jobs. Eat some Skyline Chili for me if you’re in the area, please.


Moving from Books to Topic-oriented Writing

A report from JoAnn Hackos’ talk at the Central Texas DITA Users Group meeting January 2006

JoAnn Hackos is well known in the technical writing community and is a member of the DITA Technical Committee. Recently she wrote the article asking, Is DITA Going to Tip? which explores Darwin Information Typing Architecture (DITA) in the context of an idea that will become widely accepted and popular as Malcolm Gladwell’s book The Tipping Point describes. She spoke at the Central Texas DITA User Group meeting held at BMC Software on January 25, 2006. This post contains a summary and notes from her talk. Our technical editor, Kelly Holcomb, took better notes than me, so I’m borrowing heavily from her notes for this post. 🙂 Thanks Kelly!


JoAnn’s entry point for talking about DITA and structured authoring was the transition from writing books to writing topics. She stressed the necessary paradigm shift for writers away from thinking about what they do as writing books to thinking about what they do as writing essential, correct, easily accessible, and easily digestible content that users need to perform their tasks, meet their goals, get their work done, and be home by 5 P.M. That’s everyone’s goal when using technology, hoping it will help you get something done faster to free up time for other things.

She leads us out of the book model by stressing that manuals are not books—users don’t “read” them from the first page to the last like we usually think of reading a book. They use manuals to look up necessary information. Users are not readers!

She talked about our manuals being an outgrowth from the publishing industry, and of the excitement in the profession, years ago, of being able to produce information that was actually attractive. But the influence of desktop publishing has been detrimental because we have gotten so caught up in how the information looks (formatting, sticking to a “book” structure, marrying format to function) that we tend to overlook the real needs to the users. And, all the attention to formatting detracts from what we actually do as technical communicators (the perception of outsiders of what we do has been adversely affected).

She actually held up the “About this book” type of section as an example of an artifact of publishing with no real use for our users.

So, what do customers require? Tell me if you agree, and I agree with her list:

  • Task-oriented information for getting things done
  • Minimalism: less info=no glut
  • No out-of-date information stuck in books
  • Information that is easier to find and easier to use

Topics and DITA

What are topics?

  • Discrete units of information covering a specific subject with a specific intent
  • Small enough to promote reuse across multiple contexts and output media
  • Large enough to be easily authored and large enough to be readable and coherent
  • Able to be organized into a wide variety of structure, from linear to networked

Topics allow us to provide “just enough” information to the users. Writing topics removes the interconnectedness of books and lets information stand alone. Context is not provided by a super-structure (the linear structure of the “book”), but from within the topic itself by its complete, discrete information and links to related information.

DITA supports topics through its model of concept, task, and reference topics.

Specializations in DITA help the designers communicate with the authors about what kind of information they are writing.

With DITA, writers create maps. “Maps” are what our users need—a way to get into and through the information. She talked about getting away from the straightjacket of the PDF into an information-centric web site (her vision). Such a web site allows the users to find the information they need, and find other related information. She stressed the relationships of topics: providing access to related information or prerequisite information, and letting users give feedback about what other information might be relevant to a particular topic (suggesting other related info links). She also talked about unnecessary concepts: if you can’t relate a concept to a task that the user must perform, you should question the appropriateness and relevance of providing the concept in the documentation.

Planning topics

She stressed the idea that effective topic-oriented writing requires planning and collaboration, especially if information will be produced by many writers. The lack of collaboration has traditionally led to duplication of information, as well as gaps of information, in books.

  • Begin with tasks that users must perform to reach their goals
  • Consider possible scenarios that illustrate typical user tasks in the context of real-life goals
  • Turn basic tasks into introductory tutorials

She used the AutoCAD documentation as a good example of providing brief tutorials for basic tasks (as AutoCAD users said, “teach us something in 10 minutes”). Then, she showed us how they augment the tasks/tutorials with conceptual information, often provided as videos. Then they add the reference information that is needed to support goals (their online reference command). This online Help/document provided three tabs at the top of the right-hand pane (the information pane). These tabs provide access to tasks, concepts, and reference information related to the current information.

Business case for topics

  • Topics promote minimalist agenda—fewer words to manage
  • Topics promote structured, consistent writing
  • Topics are easier to localize, further reducing costs
  • Topics enable multiple deliverables to meet the needs of diverse user communities

Manuals are tools that must be fitted to use; topics make manuals economically possible. Her story illustrating this point tells of a telephone repair technician who had to take not one but three snowmobile trips in order to repair a remote station. He didn’t lug a 500-page manual with him, as you can imagine.

Guidelines for topic-oriented writing

  • Focus on best practices in information design (as always)
  • Don’t construct elements for every bad design decision. In other words, don’t change the standards to fit your current content, but rather make your content conform to the standards
  • Develop authoring standards and guidelines, and provide example for writers
  • Demonstrate how to apply DITA elements correctly. Part of the editing process needs to look at the tags to ensure that they are used correctly. Incorrect use of tags will make reuse impossible.
  • TRANSFORM information, don’t convert it!
  • Use the transformation to harmonize topics and identify levels of reuse.

Information that came up in relation to questions asked by audience

I asked a question about the approach to implementing structured authoring, specifically analyzing content and creating models/specializations from that versus transforming information to fit in the standards and model. JoAnn’s advice: Look for the DNA of the information, the underlying structure that governs the information. Don’t try to squeeze every idiosyncrasy and every construction error ever made into the new model (transform, don’t convert).

Another audience member asked about the relationship between information mapping and DITA. They have practically identical philosophies; information mapping provides more types of information than DITA (7 versus 3), and information mapping has more to say about how information is developed, but in JoAnn’s opinion, the two methods are highly compatible. (She mentioned that the Information Mapping organization has just announced their support of DITA.)

Don Day or JoAnn also mentioned Michael Priestley’s article about scenario-based writing, which sounded interesting (illustrating a different way of approaching the content). Here’s a link to the presentation slides and article on (Thanks, Don!) or if you’re an ACM member, here’s a link to a PDF download.

Later, in a separate discussion, Kelly and I talked with Don Day about how the needs (habits) of mainframe users are unique: they love their books and have special rooms dedicated to documentation. IBM should know about those users! So, the delivery of the information is still traditional for mainframe products.

Feel free to comment on your thoughts on the meeting or the ideas presented here. I’m definitely interested in how you read manuals (or don’t read them).


EMC Adds Google Desktop to EMC Documentum Federated Search Environment

An excellent combination, Google search for your enterprise content

Yep, yet another Google-related post. I guess I can’t get away from Google lately. Documentum is the storage location for much of BMC Software’s technical documentation, and this press release announces that EMC has chosen to integrate Documentum ECI Services with Google Desktop for Enterprise. It’s based on version 5.3 and offers full-text search capability across all types of documents stored in Documentum.

I also learned from this ComputerWorld article that Documentum already supported Google Web site search and the Google Search Appliance. This announcement touts the ability to use the Google Desktop search index.

The article also says that one target for this type of search is the call center employee whose job success depends on finding answers fast. I think many of us know how helpful it is to find answers fast regardless of job description. But certainly this is a tool for keeping your help desk and service desk fast and responsive.


Google Desktop to the rescue

Wherein I admit to a completely foolish overwrite of a white paper in progress, but also tell you how Google Desktop saved my text and made my day

I was working in Word 2003 this morning on a white paper and wanted to create an outline. I deleted the body text between headings and THOUGHT I had saved the file as a new file. To my horror, I realized that I had saved over the original file. I frantically searched for .tmp files, backup files, the clipboard text in case I had copied some text, but the sinking feeling in my gut was the realization that I had truly written over the file with no hope for recovery. (I didn’t have the magical Save AutoRecover info every option (on the Tools menu, click Options, and then click the Save tab) selected as I learned on this Microsoft KnowledgeBase article.)

I’m not the first to sing the praises of Google Desktop here on, but today I discovered a great new use of the tool! In looking for pieces of my text using Google Desktop, I found that Google Desktop had cached versions of the Word file stored about every 10 minutes! So I clicked the Cached link with fingers crossed, and lo and behold, there was the text of my document. I quickly copied and pasted it into a new Word doc and heaved a sigh of relief (or was it a shout of victory? Ask my hallmates.)

Nothing left to say but WHEW.


A smart Google search to locate specifics in BMC’s tech docs

Here’s a method for searching BMC’s repository of technical documentation using Google

You can use Google’s site: search feature to look for technical documentation that’s stored on the web site. Just add to any search string that you enter in Google, and the results that are returned are only from the BMC web site in the directory where technical documentation is stored. It’s even doing full text-search within the PDF files, so it’s quite useful. Here’s a sample search string. Just enter it in the Google Search field.


Any other favorite Google search tips and tricks? My favorite collection of them is on the O’Reilly site, related to the Google Hacks book. My most used feature that Google offers has to be the automatic spelling correction it does on search strings. How about you? Any favorite Google features you’ve discovered?


Questioning technical publications best practices

List of the questions I asked of our panelists about best practices in technical publications

Here are the questions I asked of our panelists at our October STC meeting in Austin that further investigated and challenged the best practices listed in the “Tech writers as sales reps?” article on which we focused.

Over the next few weeks, I’m going to group some of the responses into different categories of “best practice” and enter a post for each. I’m just writing what I’ve taken away from the session.

The first has to do with best practices for Document Management Systems based on a question from a reader, which I’ve already posted. The second I’ll title “Best practices for connecting tech pubs to the rest of the business.” The third part will discuss best practices for staffing and suggestions for resourcing, and finally I’ll discuss best practices for structured authoring, a topic on which I think the original article missed the point. There’s a difference between single-sourcing and structured authoring, and the author doesn’t fully realize the missed potential by sticking mostly with single-sourcing.

First, the list of best practices with the questions I posed to our panel.

#2: Understand the value of good documentation.
How do you prove Return On Investment (ROI) for tech pubs at your company? Is the author’s “use customer support to prove ROI” argument a valid one in your experience?

#3: Use documentation to gain an edge.
Does this happen in reality? Do most executives share this view? How have you tried to tell your executives that your documents help you gain an edge?

#4: Have a reasonable ratio of writers to developers.
Do you agree with the author’s 8 developers for each writer approach? How do you estimate your ratios? What’s the right ratio? How have you used this ratio when asking for resources?

#5: Place technical writers somewhere sensible in your org chart.
The author places technical writers in customer support, is that the right placement to you?

#7: Encourage technical writers to meet customers. and #8: Use customer advisory boards to get feedback on documentation.
Customer interaction – discuss constraints on really making this happen. How have you made it happen?

#13: Try out conditional text.
How do you ensure it is used wisely? How do you set up standards? Is this a tool-based decision?

#14: Explore single sourcing.
Do you agree that single-sourcing is the answer? Is he using the old definition of single sourcing, where you don’t really repurpose content? Is the new idea of structured authoring where exploration should occur instead?

#9: Make the right tradeoffs.
How do you ensure that writers focus on content rather than formatting? How can an editing team ensure that the right tradeoffs are chosen? What tradeoffs are there between information quality and quantity?

#10: Pick the right medium for each deliverable. and #11: Provide print for those who need it.
The question is, how can you ignore the costs of 3,000 pages of printed documentation? How much print do each of your departments provide?


A proliferation of XML languages

Thought-provoking post about how many languages have sprung from XML

From a post to his “ongoing” weblog by Tim Bray:

Here’s a radical idea: don’t even think of making your own language until you’re sure that you can’t do the job using one of the Big Five: XHTML, DocBook, ODF, UBL, and Atom.

With details and scenarios of use for each of the Big Five. Nicely stated, yet I still think there’s room for a Big Six with DITA on that short list. Docbook supporters have discussed similarities here, so you can dig in and make your own decisions.

Thanks for the interesting link, Steve!


Attending SXSW in March 2006

Finally completed my registration for SXSW Interactive 2006

South By SouthWest (SXSW) Interactive is the web, blog, RSS, and other three letter acronym part of the SXSW conference and festival here in Austin. I finally paid the $250 registration fee (today’s the last day for that, it goes up another $50 to the walk-in registration rate after January 13th.) I’ve been once before, in 2003.

This year Jason Kottke, full-time blogger at, and Heather Armstrong, supporting her family by blogging at, are keynote speakers. I’ve been reading them for quite some time now and look forward to the keynote especially.

I hope to take away inspirations for structured authoring from a techpubs standpoint as well as online technologies that are at the heart of our user’s needs. I’ll post a full report, I’m sure. Anything in particular you’d like me to keep an eye on?


Best practices for document management systems

Complex, to be sure, document management systems are helpful to IT departments and tech pubs alike

I recently received a question about best practices for electronic document management systems using Word 2003. While I use Word 2003, I have only used it in combination with Sharepoint as a document management system, and the docs I write in Word are usually short, internal documents, not external technical manuals. Coincidentally, I’ve heard that IT departments are using document management systems in concert with their CMDB. Text-based documents, drawings, architecture designs, all these documents are important to an IT department and any business organization. It makes sense that the CMDB would be related to a document management system, although I won’t get into any discussion about whether each document is a Configuration Item (CI) or not. 😉

My experience with document management is Documentum with FrameMaker, and we don’t currently do much co-authoring with people in the rest of the company. So I’ll admit first off, this request for information is outside my personal knowledge. But, I do like a good research question and I gathered together some reading items.

Here’s a summary of what’s found in this article about putting together a document management system using Microsoft tools. Your environment may vary widely from an accounting-type environment, though, but I thought these were decent overarching goals for managing documents, and I expanded on a few of them based on my experience with document management systems in general.

  1. Determine what documents get the “document management treatment.” Create limits on what is stored and maintained in your system so that you know what’s in there and what’s not, and you also limit maintenance and a bulging file system. Will you scan and store images of paper copies?
  2. Classify or group your documents together. Some EDMSes do this for you using document type, but you might also want other criteria for easy search and retrieval later. This approach also allows you to assign more than one classification to a document.
  3. Store the files efficiently to make retrieval easy. Your EDMS might do this on its own with little input from you.
  4. Retrieve as needed, using versioning if desired, which leads to the next step. Realize that indexing and keyword searching are crucial tasks for retrieval. Be sure to train users to properly tag documents for fast and efficient retrieval. You may have to create a taxonomy using standard terms for the system.
  5. Managing and tracking documents allows for the type of collaboration where one person can check out a document to make revisions. Other collaborative activities might include activities such as participating in active discussion groups, tracking issues associated with customer engagements, maintaining common contact information for subject matter experts on a particular document, and even assigning tasks related to a particular document. Tracking and versioning also allows for storage and retrieval of documents from a point in time which may be helpful historically.

For research like this question, one place I like to do searches is There was one relevant Answer for someone who was looking for an analysis of document management software. It’s long but comprehensive. I realize you might be well past the evaluation stage for a DMS, but you might get a look at what features are offered. You can also use to search only for blog entries on a given topic, although that particular search method did not offer much on this particular topic.

Going beyond Google, I did a search using to search for blogs about “document management systems,” and the best I’ve found so far is Another site that offers a wide range of case studies and white papers is The Gilbane Report at

There are also lessons learned from the doc management trenches at Hewlett-Packard. It appears the author is Susan Charles, an Information Research Analyst at Hewlett-Packard. She describes the implementation of an internal document management project at HP. She discusses the challenges of the project, and what she sees as the lessons learned.

In addition, here’s a case study from a university setting. I haven’t read through it completely but it might offer some advice.

As with many best practices in technology, you want to analyze first and implement second. Spending more of your time in the up front planning and definitions will pay off when you go to populate your system with documents.

Anyone else have some advice to offer? Feel free to post a comment, or use the trackback URL to write about it in your own blog and refer to this entry.