How Do You Spell G-R-A-N-U-L-A-R-I-T-Y?



August 2009

How Do You Spell G-R-A-N-U-L-A-R-I-T-Y?

CIDMIconNewsletter Kathryn Showers, Symitar

Once upon a time, I was a newbie to DITA. Like most novices to the DITA world, I asked the following questions:

  • What is granularity?
  • How granular is granular?

They seemed like simple enough questions. But the answers I received were somewhat dissatisfying:

  • It depends on your documentation.
  • As granular as you want. But, be careful not to get too granular because it can become too difficult to manage.

*Heavy sigh*

Since the only way to understand granularity as it applies to our documentation was to roll up our sleeves and dig in, that’s what we did. Somehow, looking at our documentation wasn’t quite enough. Our monolithic tome was filled with system documentation. What we really needed—nay, what our clients demand—are the step-by-step procedures with which to accomplish their goals.

That was the beginning of understanding our level of granularity. We examined the specific needs of not only our clients and their staff, but our managers, program developers, Information Architect, editors, and writers as well.

What do tellers need? They need to facilitate transactions for credit union members. What do loan officers need? How different is the information they require to complete their daily tasks from what a programmer needs to write specfiles or customize the system to meet their credit union’s goals?

Looking from the outside in gave us the perspective we needed to hone in on the one aspect of our product that defined granularity for us: the fields in our system’s records. Fields are the cornerstone of understanding our product, regardless of the user. Fields have the greatest potential for reuse. We can target sub-sets of information for specific users via conditional processing. Nearly all of our documentation products use the same core field set.

Now that we know what to start with, how will the writers know what, or when, to conref? How can we manage all the little pieces without going crazy? How will the writers remember all the rules surrounding when and how to use a tag? What about me? Raging co-dependent that I am, how will I ever make everyone happy without losing my last vestiges of sanity?

The answers to all these questions did not come quickly nor without a great deal of adjusting.

How will the writers know what or when to conref?

The only way to figure out the how, what, and when of this question was to first understand the documentation we were about to migrate to XML. Sure, we had a great encyclopedia worth of documentation, but when was the last time we actually went through and read it? Not only read it, but tried to understand it?

Until you fully comprehend the substance of your documentation, you can’t begin to break it apart into reusable pieces. We read and researched our existing fields documentation and created spreadsheets to keep track of which records had identical or similar field names, and then compared each field description with the others to confirm that there was relevant information which could be shared among them.

Once the pieces were exposed, what, when, and why we conrefed which pieces into appropriate places became clear. We learned how to write it once, write it well, and then reuse it often without creating ambiguity or sacrificing meaning (see example in Figure 1).


How Can we Manage All the Little Pieces Without Going Crazy?

By scrutinizing how our clients and staff used the system, we found patterns of reuse. Even better, we saw patterns of reuse within those patterns. This process helped us solidify our approach so we could, finally, agree upon a definition of granularity we could apply to our documentation efforts.

The key: centralize common phrases. Hold on—don’t confuse this with the <ph> tag! For example, when we began to write the teller transaction tasks, we created a Master Phrase document. This became the source for all the steps, step results, paragraphs, and yes, text surrounded by the <ph> tag, which were exactly the same across multiple teller transactions. (The Master Phrase documents make our editor very happy because a large portion of her editing for a project is complete once she reviews the common phrase document. She gets a kick out of opening a topic and seeing the gray background indicating conrefs because she knows that it is text she has already edited!

How Will the Writers Remember All the Rules Surrounding When and How to Use a Tag?

A necessary part of the XML migration process is standards and procedures. You can’t build a house without a set of plans, and the same is true for building a strong set of XML documentation using the DITA standard. With blueprints in the form of a Master DITA Job Aid, our “writer/builders” were able to break ground and lay the foundation for a great set of XML documentation following the DITA standard. The job aid we created detailed each DITA tag (Figure 2), along with a comprehensive description of when the tag should be used and examples for the writer to refer to when necessary.


The Master DITA Job Aid was, and still is, a work in progress. It has evolved, and we continue to review it and make changes as we take on more projects and clarify our vision of what our documentation will become.

Any time our editor questions the use of a tag, she has only to bring me chocolate or open the Master DITA Job Aid for clarification (see example in Figure 3).


How Will I Ever Make Everyone Happy Without Losing my Last Vestiges of Sanity?

I guarantee that I won’t make everyone happy, and I most certainly will occasionally lose my sanity. I don’t think it is the responsibility of an Information Architect—or any one person—to carry all the weight of a migration. The process is a team effort, and if done correctly, can truly bond a technical publications group and transform them into better writers. Because every step of the process has been collaborative and no one person has established all the rules, then when an idea fails, no one is at fault. We make the changes necessary, clean up the debris, and start again. Without blame and regret, we journey on into the next exciting phase of XML documentation.CIDMIconNewsletter

So, then, What is Granularity and How Granular is Granular?

Well, you see, er… it depends on the needs of your users, writers, editor, IA, and managers. Oh, and your documentation.

By the way, we created this article in the very same way we write XML documentation: collaboratively.

My heartfelt thanks go to Vanessa Campbell, Kara Church, and Terry Barraclough for their patience and invaluable contributions.

About the Author


Kathryn Showers

Kathryn Showers is the Information Architect for Symitar, responsible for migrating core and peripheral product line documentation to DITA. She has a flair for enticing information from reluctant sources and into the hands of those who need it, mated with a knack for reducing highly complex concepts to easily understood elements. A mother of three children under 10, Kathryn spends her “down” time enjoying her beautiful family and scrapbooking.