Monthly Archives: September 2006


ITIL blog roundup

I offer a collection of ITIL links

For your Friday reading and perusal or for bookmarking and saving for later:

As an additional bonus, there are 17 ITIL-related podcasts on I just listened to the most recent one with Ken Turbitt and Peter Hill about ITIL vs. CoBIT. A very interesting conversation!


An outline for a passionate user guide

From “Creating Passionate Users,” Kathy Sierra follows up to her “let marketing write the manuals” post

Her post on “Creating Passionate Users” is a long one but well worth reading — How to get users to RT*M. Since this is a G-rated blog, apologies for the known acronym. Let’s say it stands for “Read The Fine Manual.”

As promised, I’m following up to my prior post “Seducing users to read the manuals” by taking a look at what Kathy has to say about creating that passionate user guide.

Since I’m currently working on information modeling which means analyzing content especially at the table of contents or outline model, I was excited to see her write a “model” of sorts for a passion-inciting user guide. I see a distinct tie between the structured authoring approach that we’re taking and the user learning and understanding that she describes.

So, what’s in her ideal user manual that inspires passion?

A good manual for a complex product should usually include at least FIVE distinct sections:

Reference Guide – The only way to really make it “stick” is by helping them ‘get it’ on a deeper level, where the mental model (thought bubble) in their head matches the one you were trying to communicate… the mental model that lets them extrapolate and infer and be creative about things that weren’t in the tutorial.

Tutorial – By “tutorial”, we mean walking the user through a concrete example of using the product to do a specific task.

Learning/Understanding – It is up to us to get the user/learner motivated to not just Open The Manual, but to want to actually… learn new things.

Cookbook/Recipe – A Cookbook/Recipe section is where a series of steps that might otherwise live in different places in the manual are all brought together under something like a “How do I…” heading.

Start Here – A “Start Here” section, which many product manuals include, is a low-intimidation way to help the new user jump in and get something happening.

Wait a minute… those sound familiar

If you read the rest of her detailed descriptions of each section, in essence, I believe she’s describing John Carroll’s basic concepts of Minimal documentation. Minimalism was first described by John Carroll as an instructional design philosophy at the IBM Watson Research Center in the 1980s, presented in his book The Nurnberg Funnel (amazon link).

The way I see it, structured authoring has a basis in minimalist principles. Minimalist principles encourage both us writers and trainers or instructors to:

  • get users up and running quickly (Start Here section)
  • let users think and improvise (Reference Guide section)
  • focus the material on real work, real goals (Cookbook or Recipe section)
  • make use of a user’s prior knowledge (Learning/Understanding sections)
  • use error recognition and error recovery as learning helpers (Ah ha! The one item Kathy missed out on but a few commenters noted the omission.)

I have to say that she seems to be describing consumer-product manuals, like your TiVo or MOTORAZR. I personally find it more realistic to get passionate and excited about consumer products than the products that I need to use to get my job done. Frankly, the docs I write are for products that people use to get their jobs done. So… I’m not convinced that her outline works well for the products that I document. Yet… it certainly offers some thought-provoking ideas and also makes me think, how can I work these types of sections into the docs I have? Will my particular audience appreciate sections that have the type of info that she’s talking about? Most likely the answer is yes. Wouldn’t we all like to be a little more passionate about the tools we use every day?

Lastly, be sure to check out the collection of links to her favorite education/learning blogs. Most of those are already on my RSS feed list, but I’ll be adding a few more to my list thanks to her roundup.

Viki Davis: Cool Cat Teacher Blog
Jay Cross: Internet Time Blog
Cognitive Daily
Judy Breck’s Golden Swamp
Usable Help
Darrren Barefoot
Boxes and Arrows
Solveig’s Open Office blog


What if users wrote the manuals?

A real world look at wikis with Wikipedia as the case study… who is creating that content, anyway?

Inner gang? Mini empires? Am I talking about the online encyclopedia, Wikipedia? Why yes, yes I am. I’m reading “Who Writes Wikipedia” which is a study on how Wikipedia is edited and maintained. Is it really “a small group of colleagues working together toward a common goal?” A small group wrote that much content in about four years?

I’m interested in this subject because Wikipedia is a wonderful reference site full of content that usually is accurate and rings of authority even though it is maintained with an all-volunteer content creation and editing team. Seeing it and liking the results, I wonder how a wiki could be used in a similar fashion to build technical documentation sites that are user-built and maintained while offering the best, most thorough, most accurate technical information about a certain product or technical subject. Could we really get as valuable a reference for product doc by having a “small group of colleagues working together towards a common goal” — a goal of an excellent set of product documentation online?

Outsiders provide content, insiders clean it up

Come to find out, according to the article, over half of the edits are done by less than 1% of the users, about 500 people are considered to be the inner circle of editors, building consistency in wording and categories while fixing typos and editing content where needed to build more quality into each entry. The most active group of about 1400 people have done nearly three-quarters of all the edits. These statistics and claims are made by Jimbo Wales, the face of Wikipedia. Now, the article’s author, Aaron Swartz, tracks a few more nuances of this claim by studying random wikipedia entries, such as the one for Alan Alda. And here is his conclusion based on his study:

When you put it all together, the story become clear: an outsider makes one edit to add a chunk of information, then insiders make several edits tweaking and reformatting it. In addition, insiders rack up thousands of edits doing things like changing the name of a category across the entire site — the kind of thing only insiders deeply care about. As a result, insiders account for the vast majority of the edits. But it’s the outsiders who provide nearly all of the content.

Wiki for tech doc

Now, I’d like to try to translate this to what might work well for a wiki geared toward product documentation. You’d need a core set of very knowledgeable content providers, like a team of experienced users of the product. Those users would contribute a core body of knowledge to the wiki, and hopefully choose to first document the items that are either most popular tasks or the most-referenced information or the toughest concepts to grasp. Most likely that would be the subject matter they’d be most familiar with anyway.

But is there vandalism?

It also appears that my wiki graffiti concerns are likely unfounded… the article says, “A tiny handful — probably around 5 out of nearly 400 — were “vandalism”: confused or malicious people adding things that simply didn’t fit, followed by someone undoing their change. That’s such a small percentage, just over a tenth of a percent, that it seems for the most part there are few writers with malicious intent in their edits.

Real wiki writers tell their experiences

Reading through the comments, I also appreciated the “user experiences” from people who are actively editing Wikipedia content. One commenter notes that he “went crazy” adding content in areas where he had knowledge but found that once his knowledge limitations were surpassed or the well was dry, he went into a maintenance mode. With a “burst of new knowledge” he’d add more content to those areas but found those to be few and far between. I think that with product documentation a similar ebb and flow would occur — knowledge or experience with a relatively new feature would cause activity on certain articles but then maintenance would occur again.

How do you get enough contributors?

Probably the major limiter for a product documentation wiki that’s maintained by users is that the user base would have to be significantly large in order to draw enough content providers. If 500 people maintain Wikipedia, you’d probably need 50,000 users to get 500 committed people to provide content (or would you actually need half a million?).

How do you ensure consistency?

Wikipedia has a basic information model to follow that most people are familiar with, also — the encyclopedia and it’s article-like writing style and the content you expect to see in an encyclopedia is well known and the style is easily copied by any writer. Product reference would need some excellent modeling to follow, which is why I lurve the idea of a DITA wiki — structured content models that 500 people could follow consistently, writing concept topics, tasks, or reference topics on a regular basis.

I’m warming up to the wiki

We can learn a lot from Wikipedia’s success and I plan to continue to track their progress as it evolves and more policy is put in place. Perhaps the wiki has potential as a great product doc format.

What do you think as a writer? Would you be willing to write and maintain content for product doc in a wiki? What do you think as a product user? Would you want to read and would you trust the content provided by thousands of fellow product users? Maybe I should experiment by combining the two groups — user and writer — and start a FrameMaker wiki. Surely the FrameMaker user base just isn’t large enough to generate the content it would need to succeed. What do you think?


Turning information into DITA topics

What would you do to make this particular type of content into topics?

I’ve been looking at content at BMC and determining whether it belongs in a concept, reference, or task topic using DITA’s definition of a topic. I had one particular item that seemed like it could be arranged in several different ways with advantages and disadvantages for each method. I had a great conversation with a fellow writer and a technical editor in the car on the way back from our corporate offices in Houston, and I thought I’d capture that discussion in a blog entry. So here goes.

Background information for this task

Overall, the user wants to configure their shiny new BMC Performance Manager for Databases product. It’s a pretty flexible configuration process to accommodate the needs of different environments but also to balance out ease of installation and configuration. So, you can either have the product automatically configure everything (you have to have certain user permissions on certain objects to do so) or you can manually configure by editing some included scripts that will give the correct permissions to each individual object (also requiring certain permissions but gives you the exact knowledge of what’s happening to your database).

So, as you might have guessed, the manual configuration goal turns out to be the toughest to turn into topics. I decided to look at the tasks related to manual configuration and then write the supporting topics.

What’s the task here?

But is the task itself “manually configuring” or is it “editing scripts?” I finally decided the task itself is editing the scripts, much to my chagrin because it doesn’t sound like a goal-oriented task. In addition, the background information for knowing why you’d do auto vs. manual should be explained in a concept topic, I believe.

But here’s where the decisions got a little tougher. The supporting reference information is a table of the objects and the required permissions on each. Obviously exactly the sort of information the DBA needs to know to get the job done. However, the complication occurs when I see this big table listing the script names — is that a second reference topic supporting the task of editing scripts? It’s only two columns but it’s a matrix of three supported databases with at least three script names for each. It’s essential information, required in order to complete the task of editing a script for manual configuration.

Do you put reference info in with the task if it’s critical for completing the task?

So do I keep that reference information with the task itself to avoid separating it into a standalone topic? Or assume the reader might come to that topic from many different directions so it should be by itself but in a related links link from the task.

Final decision – make it a topic

In the end, I decided that for ease of reuse and to offer multiple entry points to the information, I would make the script table standalone as a separate topic. It seems like the benefits are that the user can find that topic more easily and also that reference info can be related to other tasks as well. Other deliverables may also want to include that reference information so designing for re-use seems like a benefit here as well.

I’m still a little uneasy about my final decision to make four topics out of what is essentially one end-user goal — to manually configure their product. Does anyone who does topic authoring often have any suggestions?

Parting thoughts on the complexity of software documentation

This type of configuration complexity is why many examples in topic authoring presentations and articles ring hollow to me. Examples of the portability of telephone pole repair manuals and the task-orientation of cell phone manuals are not the types of concrete questions I ask myself every day when writing software doc. The classic example of “Hold the power button for 0.7 seconds” as a poor example of a step in a task immediately comes to mind. An equivalent software documentation example is much more complex than instructions for a task on a cell phone.

Software doc lives in the abstract. Instead of an easily known or recognizable metaphor, I’m faced with products that are increasingly flexible but that flexibility causes the user to be faced with many micro-decisions. I think it’s my responsibility to guide the user through their choices and offer the technical advice for them to make the best decision, no matter how they’ve approached the doc in the first place. (from a search engine? from the table of contents?) It isn’t easy but oddly enough I enjoy the hunt for the best content organization and chunking possible.


Reports and proposals in technical publications

Plus a description of what a technical writer does through an interview with a technical communication student from Miami University

I got an interesting query from Matt, a student at Miami University in Ohio, where I received my master’s degree in Scientific and Technical Communication (MTSC). Miami University also has an excellent bachelor’s degree program in Technical Communication. Matt’s a Technical Communications major from Akron, Ohio. My MTSC classmate Janel Bloch is Matt’s teacher. Matt has read my blog and has an assignment for his technical writing class where he should conduct an investigative report assignment on the types of reports and proposals written by professionals in his area of interest, which is Computer Science. So, we emailed back and forth and he came up with these interview questions. Here are my responses to his interesting questions.

What is your title at BMC Software?

My title was Information Developer II until BMC decided to standardize more job titles recently, and then my title was changed to Sr. Technical Writer. I’m not much for focusing on titles, instead I prefer to focus on the interesting nature of my assignments, so you could give me any title and as long as the work is interesting I’ll be content with any title. 🙂

What is a typical day like (I know this is probably a stupid question)

It isn’t a stupid question, I often like to ask this one when trying to find out more about a person’s job because daily activities are a good indicator of whether I’d like the job or not. So here goes…

I’m the type of person who likes to have a couple of different assignments going on at any given time, as long as I know the priorities for each and approximately how to chunk the tasks down to sizes that are manageable. I check email constantly throughout the day and try to respond immediately when supporting others in their work (such as “what’s now broken in this help system that used to work?”) I also attend about five hour-long meetings a week, which in my current corporate environment is not too many meetings compared to the number that many other writers and managers attend.

Right now, I spend about half of my day working on a user manual, whether it’s asking questions of development, making changes to the document, or trying out the user interface or command-line utilities to test procedures I’ve already written. The other part of the day I am working on the information architecture planning tasks we are working on for a DITA implementation for some pilot projects. Recently I have also been finishing up white papers that are related to Business Service Management topics. I like to have a variety of work options in front of me in a typical day.

When a product release is coming up, I focus much more on the product documentation and keep up with the development and especially quality assurance/testing team’s daily activities. So my daily routine would be much more focused on communicating with the team, finding out testing progress, and looking out for software bugs that might change the documentation.

What kinds of things do you write at work? outside of work?

At work, I write user manuals, release notes, white papers, blog entries, and painstakingly craft email messages when I need to. Often I write “how to” documents for other writers, such as how to install Epic Editor for our environment, or describe how I have found efficiencies for a certain internal procedure, such as how to zip up help files. Sometimes those get turned into blog entries even. In addition to my external blog on, I maintain an internal blog called “Geeky Tech Pubs Tips” where I post information that’s only relevant to people who work at BMC.

Outside of work, I write email messages to friends and family, I write lots of commentary for photo albums I’m maintaining of our family’s activities, and otherwise I don’t do a lot of writing. I have a secret stash of children’s book ideas though and I might get to writing those some day. I also write blog entries for our STC chapter’s blog,

What kinds of media do you use when you write? (online or print)

I nearly always have an online media in mind when I write, which may or may not be the best mindset. However, most of the products I’ve been working on tend to ship more online PDFs and HTML documents than printed documents, so I think it’s the right mindset for what I’m currently assigned to.

For white papers, though, I have a printed media in mind and page count really matters, which makes you write and do layout at the same time, paying close attention to line breaks and page breaks and graphic placement. As for the type of tools I use while writing, we use FrameMaker for printed manuals and white papers, and Dreamweaver for HTML editing. I am also using Epic Editor to write DITA topics as I do the research for our structured authoring projects. I use Word to write internal documents or early drafts of text where I might want to use the Track Changes feature.

Do you write any proposals and/or reports? Are you required to do any research?

I typically only write internal reports and can’t think of any proposals I’ve written. Wait, a few years ago I worked on a team that wrote a proposal for embedding online help into a product’s interface. So I do write proposals as part of my job description. I have done a lot of research on technologies that matter for technical publications, sometimes related to online Help presentation, sometimes related to XML implementations, and so on. I’ve written up reports and do presentations for both internal and external audiences for those types of unique projects. Determining whether to recommend JavaHelp for a certain product is an example of such a research report.

Who is in charge of reports and proposals?

I tend to think of several examples of reports and proposals in my current company’s setting. Here are some examples and who is in charge of those:

Annual reports – A summary of how the business is doing, typically written at the end of fiscal year. I’m not entirely sure who is responsible for that project.

Competitive reports – An analysis of products that compete with our products and how our products stand up against certain features or selling points. These reports are usually written by product managers who talk to customers and sales people, and they may also be written by sales people to help others sell in competitive situations.

Internal research reports – The embedded help proposal I’ve attached was written by a team of writers who researched and reported back to development what we learned about embedded help, and what we would propose should go into the product.

Internal proposals – In our environment, the one type of proposal I’m familiar with is an internal proposal or a business case for justifying an initial investment in order to gain efficiencies or better serve customers. Another example might be the business case to move to structured authoring using DITA. We might need to purchase different authoring tools for the new way of authoring, so a business case would help justify the Return On Investment (ROI) for such a purchase and change in authoring. I haven’t had to write that but our managers are writing that type of proposal.

How much time do you spend writing?

Many technical writers would agree with me that you don’t get to spend the majority of your time writing. Really, the writing time is probably less than 20% of your work time. The rest of the time you’re reading, researching, talking and communicating with team members, going to meetings, and learning as quickly as possible.

Who are your audiences?

Audience analysis is very important so this is an excellent question. For user manuals, the audience depends on the product. I’m currently working on a Recovery Management product where the audience is typically system administrators who are in charge of backing up and recovering critical databases.

White papers also have different audiences. For technical white papers that target one product line, the audience is typically the technical person implementing the information you present. For solution white papers that span multiple product lines, the audience target is closer to Vice President or Sr. Director of IT, a Director, Manager, or purchase influencer. To us, manager-level readers are seeking higher-level information such as ROI, and an implementer or technician seeks more technical details about implementation.

There are also internal audiences for some of the research-type things I write for internal use only. Typically I write for coworkers, development managers, quality assurance managers, or technical publication managers as an audience.

Do you read any scholarly or trade journals?

Currently all of my reading for educational purposes is done online via searches or using RSS feeds, so I can’t think of scholarly or trade journals I read regularly. I can refer to STC’s journals online, such as Technical Communication (their journal). Typically, however, Intercom has articles that are more relevant to my work situation. And I find myself reading white papers and attending webinars more often than I read a trade journal.

I find that the absolute best printed periodical for me is Wired Magazine. I read it regularly which means I’m making the time to read it, even if I take it with me to my doctor’s waiting rooms for prenatal care visits. 🙂 It is an excellent magazine with articles relevant to the future of communications. I also think that by reading it I can stay in touch with many members of the technical audience that I write for.

How involved are you with STC and what exactly do you do as a senior member?

To be a senior member of STC, you basically just have to be a dues-paying member for five years in a row. There aren’t extra responsibilities associated with the senior member title but it does show a commitment to the organization. I have served in several leadership roles in the Austin chapter and the Southwest Ohio chapter, such as Hospitality chair and Membership chair. There are plenty of ways to be involved, though, that don’t require a leadership role. Two of the best and most interesting volunteer things I’ve done with STC are helping to plan programs for the monthly meetings, such as brainstorming topics, requesting speakers, and coordinating locations. I also helped gather proposals and abstracts for talks for the Regional conference held in Austin three years ago which was another great volunteer position because I could read all the interesting things that people were doing in their jobs and wanting to present at the conference.

How were you involved with the MU student chapter of the STC?

Several years ago I was the student chapter advisor. I attended meetings and helped the students coordinate activities with the Southwest Ohio chapter as well as hold their own elections and meetings. I invited students to everything STC and we even ended up hosting a student reception at the national STC conference which was held in Cincinnati in 1999. I took the chapter president to conference planning meetings with me and I think she learned a lot by observing and pitching in her ideas when needed.


How to substitute your custom CSS when using DITA Open Toolkit transforms

When you want to use the DITA Open Toolkit transforms but you want to use your own CSS, here’s how to substitute your CSS for HTML Help (CHM)

Here’s how I was able to substitute my own CSS (Cascading Style Sheet) file when using the DITA transforms to make compiled help files (CHM). I did several Google and Yahoo Group searches in the dita-users group for phrases like “switch css chm” and “substitute css chm” but didn’t find quite what I was looking for, so I decided to try a few things and write it up. After figuring it out, I did find the topic covered for XHTML in the DITA Open ToolKit User Guide and it contains all the information I needed to make it work for CHM. I just needed to leave that “CHM” keyword out of the search phrases I was using! Go figure.

Here’s an overview of what I did to get it to work in my environment on Windows. This process should work for other platforms as well.

First, create a CSS file that contains the modifications you want for styling your output. I basically took the generated CSS commonltr.css and made modifications to that file, then saved it as a new CSS file called bmc_dita_chm.css.

Second, make sure you can build using Ant and create your own Ant script using the ant/template_htmlhelp.xml file provided with the DITA Open Toolkit. Basically, you take the ant/template_htmlhelp.xml file and substitute your project names in the file, then save the file with a new name such as build_htmlhelp.xml. Then you go to a command prompt and type ant -f build_htmlhelp.xml. You should get output with the default CSS styling.

Next, modify your Ant build script with the following parameters: args.copycss, args.css, and args.csspath. All these parameters are documented in the Open Toolkit but I still wanted a code example that put it all together. So here it is, and you can copy and paste this into your Ant build file for HTML Help (CHM).

<property name="args.copycss" value="yes"/>

<property name="args.css"

<property name="args.csspath" value="css"/>

Now your CSS file will be substituted before the compile command occurs, which was like magic to me. I had originally thought I’d have to do a command-line method with quick file copies at the right times, but these Ant builds are da bomb. The more I learn about using Ant to build DITA output the more excited I am about the possibilities. Put your DTD specialization files anywhere! And then point to them using the catalog-dita_template.xml file! And then build output from anywhere! And substitute your own CSS!

Recently there has been a discussion on the dita-users Yahoo Group about styling the CSS for the Table of Contents (TOC) for the XHTML output, and there’s now a patch that enables the substitution of your own CSS for the Table of Contents. The .patch file is for use with a GNU utility called patch (Windows version is downloadable from, but you can also read the .patch file to figure out which modifications to make where.

Have fun with your own customizations. Let us know if you have any other tips and tricks with customizing the DITA output.


Lots of tech pubs and content management conferences this fall

For example, the FrameMaker Chautauqua is local to Austin in November

There are plenty of tech pubs related conferences to attend this fall. This is by no means a thorough listing but these three have caught my eye recently.

There’s the CM Pros Fall 2006 Summit discussing Content Management and the World Enterprise at the end of November (Nov 27) in Boston (early bird registration by the end of September). It’s held in conjunction with the Gilbane Conference on Content Technologies conference so there’s sure to be a neat mix of attendees and sessions.

The FrameMaker Chautauqua is in Austin November 8-10, 2006. Wikipedia has a nice chautauqua entry, loosely interpreted, it’s a traveling meeting designed to educate. The conference is located out by our airport but don’t let that stop you from coming downtown to eat and enjoy some live music. It’ll be a little late in the season for the bats under the Congress Avenue bridge, unfortunately, but Austin has much more than bats to offer travellers. In the spirit of Keeping Austin Weird, there’s an Austin Segway tour, an Duck boat tour in Austn, and an Austin Ghost tour. There are plenty other fun things to do in Austin so please do take a look around when you’re here. Try Zilker Park, Mount Bonnell, Lake Travis, and 4th Street for starters.

There’s also the Documentation & Training Conference in Boston in early October (Oct. 3-5) and a few members from BMC’s Information Design and Development group are presenting a case study on Structuring an Organization for Customer Focus. Julia Osgood is one of the presenters. She and I worked together on our Routes To Value documentation team last year. Go and learn about our lessons learned while re-inventing the organization of tech pubs groups.


Free discovery tool for Dell battery recall

BMC is offering a discovery extension for the battery recall

Wow, this discovery extension for Marimba is just what we were talking about last week when Facing the Dell laptop with a Sony battery recall… can a CMDB help? I think that our conclusion was, tracking that information in your CMDB without discovery doesn’t give you the efficiency gains you’d want. But here’s where discovery steps in. From an internal announcement: “ BMC Configuration Management (Marimba) is offering a free extension to our agent-based BMC Configuration Discovery product. The free extension modifies existing functionality to allow users to accurately discover and report on faulty Dell batteries throughout their extended environment.

To get this free extension, please contact the Configuration Management support organization at 888-930-5556 or email for details on obtaining and deploying the Configuration Discovery extension.”