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