Serving an author's needs

In summary, this post explores writing DITA topics that serve the purposes of the author (to improve writing efficiency and minimize the topic maintenance task) and end user (to accomplish a real-world task or solve a real-world problem). As an example, this post explains how I reverse engineered a recent manual to discover other ways to group topics in DITAmaps.

Throw-away DITAmaps

As a long-time technical writer, I naturally organize information into a book with installation, usage, troubleshooting and reference sections. The early questions I generally ask a product manager or chief engineer include: Who is your customer? What problem was your product intended to solve? How will your customer use your gizmo to achieve a business or personal goal?

Once I’ve collected the answers to these questions, I organize the book’s chapters based on user needs and perceptions and begin writing from beginning to end.

This procedure worked well until single-sourcing and DITA came along. DITA’s power is be found in the simplicity of its topic types and the flexibility of its DITAmaps. Rather than initially create a DITAmap that follows the outline of a standard book, authors can create any number of maps, some to keep and use to generate output; others to throw away when they are no longer needed. But why would an author create a DITAmap that wasn’t organized to be a book or a help system? What other possible use could a DITAmap have?

The consultant who is working with us as we move from writing standalone documents to DITA challenged me when she said that I could organize my topics to suit my needs. Later, I could create another DITAmap that would reflect the needs of the user. But, what are my needs? I have always thought of myself as a user of the material I am documenting and a strong advocate for the ultimate customer. How might my needs differ from those of the reader of my manual?

Recently, I gathered information for a manual by data-mining a recorded presentation made by the development company who wrote the code for the particular feature I was documenting. The presenter had obviously done a lot of testing to make sure the code worked. What he presented was largely a testing sequence, which did not necessarily represent how a real-life user would achieve a real-life goal with the feature. I dutifully reorganized the material using bits over here and other bits over there in the resulting manual. Reflecting on that process I ask myself, what if I had simply made a DITAmap of the material covered by the presentation, breaking the information down into topics without worrying about the ultimate deliverable? Would I have avoided redundant material? Would I have identified reusable topics? What benefit would such a DITAmap have served?

Intuitively, I conclude that, at the least, the process would have engaged me mentally with the material at a deeper level than is possible when hearing a presentation or reading a specification. The process of writing about a new subject is an educational one. Creating a DITAmap of the logical progression represented by the brain dump of an engineer may be very useful.

But, starting a writing project without keeping the ultimate deliverable in mind feels dangerous. Generating multiple DITAmaps feels like a loss of control. How will I keep track of them all? How will I know if I have covered all the user-important topics? Time could be wasted. Important information could be missed.

Reverse-engineering a document

For my latest project I started out with a DITA Bookmap that follows a standard outline for a user guide. Inevitably, as I learned about the product, the outline required revision. I added and deleted topics, changed headings and rewrote material. At this point the document is in its first review and I realize that it needs additional organizational changes.

In the throes of writing this guide I lost sight of making topics reusable. Lost in the trees, I could no longer see the forest. “I will have to go back when this is all over and edit my topics with reuse in mind,” I thought.

Before making the reuse pass I decided to take the structure apart and make a set of DITAmaps out of the topics that might have served me better as the author and perhaps saved the reorganization and rework time.

First I printed out the document and began to read it. Immediately, I found material that appears twice in the document, once at the beginning in summary form, and later in more detail. I decided that the goal of this re-imagine-ing exercise should be to discover a way to facilitate writing and topic maintenance. A governing principle should be to establish, from the beginning of the process, on source of truth for each piece of information.

I thought about reorganizing the material by source. I imagined one DITAmap for topics derived from existing help system topics; another named for the engineer who provided the information; and a third for the marketing product manager who talked me through a product use case.

This felt like it would require too much ex post facto research so I took a different approach, creating a set of DITAmaps based on product functionality. Each map contains concept, task and reference topics that are related to a function within the system. We are calling them my “maintenance” DITAmaps because, should a feature change, I could use them to update all related material without having to search the manual for related information.

Would I have come up with this organization at the beginning? Maybe. Would I have avoided writing and rewriting as I learned the topic? Maybe. I’ll try it next time.

(Another way topics might be organized could be by “big” user step. In this case, each DITAmap might include topics that cover: conceptual understanding, preparation, execution, and result with a separate DITAmap for reference material.)

Dumming down authoring?

I have a lurking fear that the end result of implementing DITA will be an authoring process that can be performed by a chimpanzee running a pre-defined system. I exaggerate. But, early on in my career I realized that one of my skills was an ability to hold the entire story about a product in my brain all at once, making connections between topics without the help of a formal written outline or plan. I enjoyed the mental exercise involved. DITA and the inevitable need to improve writing efficiency have changed my mental focus.

DITA promises to improve authoring efficiency and promote collaboration, which will speed time-to-market. As in manufacturing, asking authors to work on smaller and smaller document components could simplify the process to the point where it becomes boring. But technical writing isn't there yet. At the moment, DITA is forcing bigger picture thinking. Authors have to write for reuse. Using DITAmaps to collect related topics before writing begins might help to clarify thinking earlier in the creative process, providing a significant mental challenge that can be transformational indeed!

Here goes…

The only way to find out if this new way of writing works is to try it. Next week I begin a new project documenting a software feature. Stay tuned…

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Define user goals

Now that we had a good idea of what had gone before, and we had the list of topics that we thought should be included in the new driver document, we decided to take the advice of all the gurus in this field and solicit input from our user community.

You might say that this should be the first step in the process, but better late than never! And any implementation of a new way of doing things into a department that has been churning out thousands of pages of helpful information for years is bound to be messy


Lacking time to survey real live users, we decided to email a Word document with questions to the product manager and another marketing person who have customer contact.

We asked the following questions:

  • What are the user’s personal goals? The idea here is to understand what the user perceives as his or her goal, not the goal of the driver itself.
  • What are the user’s business goals? We made clear that this question is not about the company’s business goal that motivated investment in the development of the driver. What we wanted to understand is how the existence of the driver helps to meet the end user’s goal.
  • What tasks does the user need to complete to achieve their goals? Now we’re beginning to learn about the driver and what steps need to be taken to install it and configure its options.
  • When and under what conditions are tasks performed? This question is designed to determine the limitations or restrictions to achieving the ultimate user goals.
  • What are the potential distractions to accomplishing the goal? The answer to this question begins the troubleshooting section.


We gathered only a minor amount of information from distributing the Word document. Our results improved when we included the two marketing people in the conference call where we discussed the results. As a result of that call, we reorganized and re-titled our topics.

It would have been better to talk to actual users, but we did learn a lot from the marketing people.

A best practice would be to understand as much about the topic to be documented as possible, then sit down with a couple of real users, or the next best interviewees, your marketing representative(s), and talk about the questions.

Currently rated 3.0 by 5 people

  • Currently 3/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5

Writing for use

More an art than a science, writing useful technical materials requires audience knowledge, imagination and practical experience with a product or service. Technical writers are often required to write about products before the products even exist. Writing "technical fiction" demands an active imagination. What kinds of problems might people encounter? What questions are they likely to ask?

Product engineers know the answers to the basic questions, such as, where is the power switch located? But when called upon to write materials for novice users, they rarely consider the plight of the poor person who has not lived with the product for a year, as they have. Invariaby, engineer writers opine about super-duper features or aspects of the product they themselves find confusing.

Does this describe you? Before you put fingers to keyboard (alias pen to paper) for your next user manual, talk to at least one real user. If you don't have access to a real user, at least do a simple usability test: ask your girlfriend/boyfriend/wife/husband to perform a simple task using your product. Don't coach them. See what problems they encounter. Take notes. Sleep on your findings. The next day you'll have insights you never would have noticed otherwise. Then start writing.

Be the first to rate this post

  • Currently 0/5 Stars.
  • 1
  • 2
  • 3
  • 4
  • 5