February PDX DITA Book Club meeting recap: Concept Topics and Reference Topics

We had a larger group for our second installation of the PDX DITA Book Club on February 17th, including a student from the Masters of Science in Technical Writing program at Portland State University and DITA enthusiasts from Jive Software, Netapp, and Harmonic. We discussed chapters 3 and 4 of DITA Best Practices at this meeting.

Here are the highlights!

book club

Chapter 3 reviewed concept topics and inspired conversations about what kind of topics we use the most (and what kind of topics we think we should use more):

  • We discussed using concept topics for information for beginners and targeting tasks to users with more experience. Beginners can be referred to concept topics for more information.
  • This led to one of the most interesting discussions from the evening, regarding how we refer those beginners to the concept topics that could help them. Even though it isn’t best practice, some of us admitted to adding cross-reference links directly in task steps or concept paragraphs, while some are big proponents of using <related-links>.
  • We discussed <sl>, <dl>, <ol>, and <term>, and the best uses for each. Most of us don’t tend to use <ol> but could see how it might be useful for workflows and rankings. We shared examples of when we used a <dl> instead of a <table> and why we decided on one over the other.

Chapter 4 reviewed reference topics (facts without explanations!):

  • We all use reference topics in different amounts, depending on our documentation needs. Some find references very useful for documenting UI, and others find less need for them.
  • We also discussed <properties> tables and <syntaxdiagram>.

Couldn’t make it to the meeting but have something to add? Do you want to weigh in on linking directly in steps or paragraphs versus using <related-links>? Discuss in the comments!

More people are coming to every meeting! You should join us for the next PDX DITA Book Club meeting:
Where: Jive Software, 915 SW Stark Street, Portland, OR
When: March 16, 2016 from 5:00 to 6:00 pm
What: Chapter 6 of DITA Best Practices
RSVP: Email docs@jivesoftware.com

January PDX DITA Book Club meeting recap: Topic-Based Writing in DITA and Task Topics

The PDX DITA Book Club is off to a great start! Five DITA enthusiasts from companies such as Jive Software and Netapp met for the first time on January 20th and discussed the first two chapters of DITA Best Practices.

We even grabbed a laptop and tested out a tag or two. Here are the highlights!

book club

The first two chapters touched on tags, specifically task tags, which inspired conversation about how we use certain tags:

  • Info tag: There’s so much to say about the info tag! The biggest takeaway, though, is that it’s not cheating to wrap an info tag around a note tag to get a note to appear in a step.
  • Context vs. stepsection: Most of us use the context tag regularly but haven’t explored stepsection as much. We thought that it could be very useful to split up a long topic.
  • Importance attribute: We checked out the different values that you can apply to the importance attribute. Optional! Default! Deprecated! So many choices!

We also had some interesting discussions about how DITA influences the way we work:

  • Topic titles: The book counseled to make your titles meaningful, and we talked about how we do that every day. Basically, think, but don’t overthink. Be consistent when it makes sense to be, but be clear first.
  • Task analysis: Some of us had done task analyses at the beginning of large projects but, in general, couldn’t find a place for them in the daily workflow.
  • Task, concept, reference: We commiserated about starting to write a topic and changing the type halfway through.
  • Topic-based authoring: The book had a concise section on minimalist writing. We all strive for this all the time, so it was fascinating to take a step back and talk about it with fellow writers. We agreed that a single task should generally have 10 steps or less. It is better to split up a long process into multiple task topics that are tied together by a supertask parent topic than to overwhelm your reader with a long topic.

Couldn’t make it to the meeting but have something to add? Do you use the stepsection tag or the importance attribute? Do you do task analysis as part of your daily writing process? Discuss in the comments!

Even if you missed the first one, join us for the next PDX DITA Book Club meeting:
Where: Jive Software, 915 SW Stark Street, Portland, OR
When: February 17, 2016 from 5:00 to 6:00 pm
What: Chapters 3 and 4 of DITA Best Practices
RSVP: Email docs@jivesoftware.com

PDX DITA Book Club starting in January 2016

PDX DITA is starting a DITA Book Club in January 2016, open to anyone interested in reading and discussing DITA Best Practices.

All levels welcome!
If you are new to DITA, learn along with us!
If you have DITA experience, join us in looking at the basics from a new perspective.

Where: Jive Software, 915 SW Stark Street, Portland, OR
When: January 20, 2016 from 5:00 to 6:00 pm
What: Chapters 1 and 2 of DITA Best Practices

We are looking to schedule future DITA Book Club meetings on the third Wednesday of every month. Information about future meetings will be posted on this website.

Please note, this meeting time will be reserved for discussing the latest two chapters in DITA Best Practices. If you have general questions and interest in DITA, please attend one of our regular quarterly meetings!

October Meeting: Faceted Search with DITA

At our October meeting last week, Roger Hadley and the technical communications team at Fiserv, a global financial service company with an office in Hillsboro, presented to a full house of PDX DITA users from such companies as Cisco, NetApp, InfoParse, and Harmonic.

Roger demos an interesting feature for the crowd

Roger walked us through Fiserv’s implementation of faceted search that relies on DITA metadata and a SQL search server to search their 5,000 help topics. There is one search box to enter search terms and results are listed in a center pane containing links to help topics; you can further refine the results using filters shown in the left sidebar that are based on their metadata labels of Feature, Function, and Role.


The Stats

This awesome project took:

  • A team of 8 (5 writers, 1 lead, 1 architect, and 1 manager)
  • One year of planning
  • One year to implement

And some quick stats about their documentation ecosystem:

  • 5,000 xml topics
  • 6 product categories (each built from their own map)
  • Hundreds of conrefs and keyrefs embedded in the xml files
  • Filters based on the following:
    • Feature — 34 keywords
    • Function — 90 keywords
    • Role — 20 keywords

Planning and Implementation

To complete this project, the team:

  • Researched what their users needed from a better search experience (they had been hearing over the years that the search was getting worse and worse as their content was increasing)
  • Determined that a DITA metadata/SQL Search Server approach could yield a simpler and more accurate search experience


  • Decided that faceted search based on their existing tags for Feature, Function, and Role would best optimize search results for their particular content set
  • Created a homegrown utility that showed their Feature, Function, and Role tags so writers could easily add them to the top of each xml file
  • Manually edited all 5,000 help topics and tagged them with the appropriate Feature, Function, and Role metadata attributes

SQL/MS Search Server Work

The team used Microsoft Search Server Express to index pages based on their metadata. A SQL index file built during the XHTML transformation for each map/product, is used to populate a database of pages for each product. Breadcrumbs, navigation, and metadata-based search links are added to each content page based on the information in the SQL database, as well as the metadata in each page, via PHP.

Microsoft Search Server Express offered some built-in features that they used out-of-the-box or with relatively straightforward customization, such as:

  • Provides a single box on the search home page to enter search terms (which then searches all 25,000 topics)
  • Shows a list of search results in the form of links to help topics below the search box
  • Builds a TOC-like hierarchy in the left sidebar based on Feature, Function, and Role which you can refine results by


Join Us!

We hope you’ll join us December 2nd when we host a joint meeting with our local chapter of Write the Docs.

shortdesc: an exploration

At the June meetup of PDX DITA I presented a brief talk about the <shortdesc> element, which had been puzzling me for a long time. Due to tragic audio failure, several remote attendees couldn’t tune in, so I promised a blog rendition of the talk. The post below is not a strict transcription, but it attempts to capture most of the main points, including some that emerged during the Q&A.


[meets] deep but possibly unacknowledged needs

–Don Day, http://ditaperday.com/blog/the-shortdesc-element/

 perhaps the most versatile and yet most challenging element to write for

–Laura Bellamy, Michelle Carey, and Jenifer Schlotfeldt,
DITA Best Practices

As the quotations above suggest, the humble <shortdesc> element has inspired a surprising amount of passion in writers about DITA. Pretty grandiose for a piece of text that’s often ignored and when it isn’t, takes up at most a couple of sentences per topic. Why is the shortdesc such an object of mystery?

I’m not sure I have an answer, so let’s start with a few non-mysterious facts.

What is <shortdesc>?

The shortdesc:

  • Is an optional element that precedes the topic body in a topic
  • Provides clues about topic content (enabling the “progressive disclosure model”–readers can scan it to see if they want to read on)
  • Shows up in search results and link previews as well as the body of the topic
Here are a few things the shortdesc isn’t (or shouldn’t be):
  • A  lead-in or introduction
  • A promise about the contents of the topic
  • A sentence fragment

Why use <shortdesc>?

None of these facts really gets at what the shortdesc is for.  Here is the OASIS reference’s summation of the purpose, which goes a little farther in explaining where the shortdesc shows up, but doesn’t quite get to the heart of things.

The short description, which represents the purpose or theme of the topic, is also intended to be used as a link preview and for searching. When used within a DITA map, the short description of the <topicref> can be used to override the short description in the topic. http://docs.oasis-open.org/dita/v1.1/OS/langspec/langref/shortdesc.html

What is implied here, but not quite said, is that the shortdesc should answer the “so what”? question–in other words, what is the value in this topic, and why should I care about it? The shortdesc should either try and deflect the need to actually read the topic, by extracting the key and most actionable piece of information (especially effective with tasks), or it should attempt to help a reader decide whether this topic will actually be useful enough to be worth reading. The best case is that you can mouse over a shortdesc or find it in a mini-TOC and actually find the key detail you need without reading further–and there are topics that might well consist entirely of the shortdesc. (Imagine a topic of which the shortdesc is “You should install Service Pack 3 before attempting to install the latest version; otherwise your installation will fail.”) But the second best case is that you can tell whether or not this is the topic YOU need to read. For example, a shortdesc to a longer topic with several paragraphs might specify use case information about where the information is applicable. For example, a shortdesc that says “Users who need to use this technology in a distributed environment should understand the flow of information between servers.” You can achieve some of these goals by writing clear titles–but shortdescs give you a lot more space.

Because the content of shortdesc is promoted in search and shows up in a number of places as described below, making the shortdesc valuable in itself or a clear indicator of where to find value is very useful.

Where Does <shortdesc> Show Up?

<shortdesc> shows up helpfully in many places:
  • At the top of the topic in output
  • When you mouse over a cross-ref to the topic in HTML
  • In a mini-toc inside a top-level topic with several topics nested underneath it
  • In search results (internal to a Help system, or in a search engine)

The Need for Consistency

This multi-usefulness, however, creates consistency problems. If you don’t use a shortdesc in EVERY topic, you’ll see mini-TOCs in your output with gaps in them. If some of your short descriptions are sentence fragments, or if some are very long and some are very short, or if they use very different sentence structure, you can find yourself inadvertently creating TOCs with faulty parallelism. This isn’t the end of the world in terms of usability, but it looks sloppy and will annoy people who should be paying attention to your fantastic content.


Some Technical Limitations

<shortdesc> can’t contain any of the following items, so you can’t get too fancy with them. It’s best to think of them as a text-only element since they can’t have:
  • Conditional formatting (use <abstract> if you need to do this)
  • x-refs
  • codeblocks, lists, tables, or other fancy formatting

Challenges of <shortdesc>, Summarized

<shortdesc> is going to work best if your DITA implementation is already working well. If your content isn’t well-structured and concise with a clear purpose for each topic (concept, task, and reference) and a modular structure, it will be hard to write a clear shortdesc–in fact, difficulty in writing a shortdesc may be an early warning about content problems. If your team isn’t working with a clear idea of how to write a shortdesc, you’ll end up with consistency problems, so you need to communicate about what you’re doing. And if you have a lot of legacy content, you may find yourself writing this element in bulk which is probably not most people’s idea of fun.

Most of all, the <shortdesc> element needs to function in multiple contexts and be used consistently. Otherwise you’ll end up with confusing search results or hover text, and mini-TOCs that are gappy or not especially helpful. As we learned in our meetup this June, some people just decide not to deal with this tricky element.

Tips for Success

Nevertheless, <shortdesc> can have a lot of utility in highlighting valuable content. Here are some tips to make yours effective.

  • Use complete sentences.
  • Make sure your content can either stand alone (in which case consider formatting it distinctively in the output) or that it works as the opening of the topic.
  • Don’t be long-winded.
  • Use a consistent sentence structure. Statements work best.
  • Try and offer a takeaway that relieves someone from reading.
  • Don’t promise (e.g. “the following methods work:)
  • Be systematic in getting them done.
  • If a topic contains only one sentence, just make it the shortdesc.
  • If you have them, make shortdescs for “container topics” cover the nested topics succinctly.

How About You?

In our meetup, we learned that most people in our group are using <shortdesc> fairly traditionally, as described above, or else not using it at all. However, we keep hearing rumors about creative uses including special formatting and tool tips. If you have some ingenious ideas about how to use them, we’d love to hear from you in comments or at our next meetup.












Topic for June Meeting: Video Plugin for the DITA OT

Sean Healy is going to talk to us about a plugin he created:

It’s a small, Open Toolkit plugin that allows users to review and insert video segments into DITA source. Video can be made granular just like “chunked” DITA. For visual learners, this is of some value. The video reference leverages the xref tag, so the DITA source remains valid wherever the xref tag is valid. The output is HTML5 for <video/>, <audio/>, and <canvas/>, which leverages an HTML5 browser. More info is here: http://seanjhealy.com/lab/ovid-user-guide-for-html5-video/ .

Thanks Sean, and we look forward to this discussion!

Call for speakers!

Our PDXDITA group has been active quarterly for over a year now and we’re ready to hear from YOU. Is there something about DITA that gets you excited? Then let’s hear it! We want to continue to learn from each other. Even if you just want to listen, we hope to see you at our June 12th meeting!
If you haven’t been coming to our meetings, but have wanted to, then leave a comment about what’s stopping you.

Looking for Presenters for the January Meeting of PDXDITA

We’d love to hear how you are using DITA at your workplace and any current challenges you’re facing. Or maybe you’ve used DITA in an interesting way that others might find useful. Some potential ideas:

  • Are you using the new toolkit? Has the transition from old to new caused any problems you solved?
  • Are you using filtered builds with the new toolkit? Were there any roadblocks or challenges?
  • Are other departments using DITA? What are your use cases and how did you go about getting adoption for DITA?
  • Are you doing something unique with DITA?