Using ditamaps to provide reuse visibility

A CMS provides multiple ways to access topics, and multiple ways to reuse information, but a major barrier to successful reuse is communication among authors. Each writer must have a way to learn about topics that are available for reuse. We have decided to create a DITAmap of potential shared content based on the type of information to be reused. For example, all hardware manuals may share common topics. The same goes for driver manuals and software applications.

We created a folder in our CMS to contain ditamaps that are used for purposes other than to create deliverables. For example, this folder contains drivers.ditamap, hardware.ditamap, etc. Contained within each ditamap are complete topics that can be reused as well as topics that contain the source elements for content references (conrefs).

Each topic that contains the source of a conref is meant to also contain any derivitives that may be created based on that conref. This not only provides a logical place from which to reference reusable conref, but also visibility into how information is used to derive new information. Frequently, only a few words require changing because of the context in which a reusable chunk of information appears. Storing related conrefs in the same topic makes them easier to find and reuse.

Be the first to rate this post

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

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

Implemeting DITA

This Spring one of the documentation teams to which I began implementing a Content Management System with the goal of converting all documentation to DITA-based topics. At this point the server for the CMS is running and most of the team has completed the online training in how to use the writing tools. Now the fun begins! Now we must establish editorial policies and figure out how to create reusable topics.

Our first assignment was to take an existing manual and create an outline for how to break it into topics. As a result, we realized how unique most of our topics are, providing little opportunity for reuse. I am a bit behind this process due to deadlines. The manual I am working on, however, reuses material from other books. In the daily stress of meeting deadlines it is hard to make the time to analyze content. But, the analysis step is vital to the success of the project.

 

Currently rated 1.8 by 5 people

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