May PDX DITA Book Club recap: Short Descriptions

We discussed Chapter 5: Short Descriptions of DITA Best Practices at the May 18th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Jive Software, NetApp, Daimler, and PSU’s Technical Writing program.

book club

Personally, my favorite thing about short descriptions is the way they show up in mini-TOCs. I love being able to easily view a summary of the information in a set of topics. It helps me organize my information, and it helps readers know what to expect, too.

While it seems like there isn’t much we could add to the illuminating and in-depth presentation and blog post that Marya DeVoto did on short descriptions, here are some highlights from the meeting!

  • A helpful short description could make it so that an advanced user wouldn’t even have to read the topic.
  • To a similar point, sometimes the short description IS the whole topic, and that’s okay.
  • Short descriptions should be readable on their own. Avoid introducing lists in a short description, and refer to other topics by name instead of by “previous topic” or “next topic.”
  • Being consistent in applying short descriptions helps search results.

Some great final advice from Marya–if your topics are well-structured, your short descriptions should be easy to write. If you are having difficulty writing it, take a second look at your topic and make sure it contains only one point or task.

Couldn’t make it to the meeting but have something to add? What’s your favorite thing about short descriptions? 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: June 22, 2016 from 5:00 to 6:00 pm
What: Chapter 8 and 9 of DITA Best Practices
RSVP: Email

April PDX DITA Book Club meeting recap: Linking

We discussed Chapter 7: Linking of DITA Best Practices at the April 20th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Jive Software, ADP, Daimler, and PSU’s Technical Writing program.

Here are the highlights!

book club

Inline links
We discussed how behavior influences inline links. Readers today are accustomed to inline links because of sites that use them heavily, like Wikipedia. Since readers have become somewhat immune to them, they are neither particularly disruptive nor do they appear that much more important than the surrounding text.

Still, we agreed that it is best to be selective when using inline links and to take advantage of the automatic ways you can create links with DITA, such as the sequence collection type. Toni’s team even implemented an “avoid inline links” policy.

Rel tables
Some of us use them; some of us don’t; and a few of us would like to try.
Advice for starting small with rel tables: They can be added to sub-ditamaps, as long as that sub-ditamap is above all of the links in your rel table. Putting rel tables at the sub-ditamap level also keeps them portable.

Collection types
The collection type we all thought would be the most useful (and some of us take advantage of) is sequence, especially for very long processes and wizards.

Scope attribute
The scope attribute on a link tells your .xslt where to look for the link. The peer attribute is useful when the topic you are linking to is not currently published, so the link will not break your build.

Couldn’t make it to the meeting but have something to add? Do you want to tell about your linking strategy or expound your love of rel tables (looking at you, Josh!)? 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: May 18, 2016 from 5:00 to 6:00 pm
What: Chapter 5 of DITA Best Practices
RSVP: Email

March PDX DITA Book Club meeting recap: DITA Maps and Navigation

We discussed Chapter 6: DITA Maps and Navigation of DITA Best Practices at the March 16th meeting of the PDX DITA Book Club. The book club members provided great insight. Members included DITA enthusiasts from Jive Software, Netapp, Harmonic, and ADP.

Here are the highlights!

book club

We started by talking about information modeling:

  • Marya tried to install the IBM Information Architecture Workbench software discussed in the chapter, but it wasn’t compatible with her 64-bit computer. No one at the meeting had experience with it. Have you ever used it? Let us know what you think in the comments!
  • When first starting a large project, Josh used a digital sticky-note tool to organize information, and Marya and Leona used actual sticky notes when reorganizing their doc sets a few years ago.
  • We all agreed that it is difficult to figure out how to use modeling tools when you inherit docs or are in the middle of a project. For a team starting out fresh, information modeling seems crucial, whether you use software or sticky notes (or sticky-note software).

We were introduced to new tags and elements by our fellow book club members:

  • Josh introduced us to the “resource-only” tag. You can tag a topicref as “resource-only” when you want to refer to a topic from another ditamap but don’t want the topic pulled into your current ditamap.
  • Toni introduced us to the <topichead> element. If you want a heading in your TOC but don’t want to create a topic just to get it in there, you can add a <topichead> to a ditamap. This reduces the need for one-sentence summary topics created only to get a heading into your TOC. However, <topichead> does not generate a landing page with mini-TOC grabbed from topic titles and short descriptions, so you’ll need to weigh your need for a mini-TOC against your need for a topic-less heading.

We discussed ditamap ownership:

  • Whether or not a team has someone responsible for creating the structure of its ditamaps depends largely on the size of the team.
  • A small team can spread ditamap ownership over the whole team, allowing all team members to get involved. This is a joy to some on small teams, and it is also a necessity.
  • A large team needs ditamap owners for consistency across the team.
  • Josh’s team has Book Captains who are responsible for the published book at the end of a project and for the ditamap structure at the beginning of it.


We considered good use cases for submaps:

  • Submaps make reusing maps easy. Content reuse at its best!
  • We also really like the mini-TOCs that are automatically created when using submaps.
  • Kate creates ditamap templates for her teammates, complete with recommended submaps, for consistency across her team.

We figured out who uses bookmaps (and who doesn’t):

  • This chapter of the book advocated creating a bookmap for PDF output and a ditamap for other outputs. Since bookmaps can handle other outputs than PDF, and since ditamaps can handle PDF output, the group didn’t think it was necessary.
  • Tech writers for hardware docs tend to use bookmaps, because their readers rely on PDF output and may be in a place where there isn’t internet or a computer nearby.
  • Tech writers for software docs tend to stick with ditamaps, but most of the software tech writers present still made PDFs available from their ditamaps.

Couldn’t make it to the meeting but have something to add? Do you want to weigh in on bookmaps and submaps? 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: April 20, 2016 from 5:00 to 6:00 pm
What: Chapter 7 of DITA Best Practices
RSVP: Email

Defending DITA: a Recap

Last night the PDX DITA faithful met to discuss recent noise about where DITA fits into a world where new developer-friendly tools are proliferating and gaining more functionality, and where some CMS vendors have been suggesting that CMS functionality makes DITA unnecessary and perhaps obsolete. To be fair, everyone at the table is working in DITA so we’re not free of bias, but it was interesting to talk about which use cases work for DITA and which don’t, and some of the reasons why other people don’t find DITA compelling.

A few themes emerged from the discussion:

–DITA has a lot of complexity and a big learning curve, but most of us have experienced the same problem with any tools as soon as the complexity and scale of projects increases. For a small project without a lot of content reuse, or multiple editions and versions in flight at once, or just a few writers, most tools do pretty well; when you start scaling up, you get into challenges and the workflows get less simple.

–It’s hard for people who don’t maintain information at scale and over time to understand how maintaining it can be as challenging and complex as maintaining code. Because most writing is ad hoc, created by non-specialists, and serves only one audience at a time, people who aren’t content or tech docs professionals are attracted to tools that present writing as text without apparatus. (A number of attendees had experience with showing someone in another job function the Oxygen XML editing interface and watching them recoil.)

–But those of us who are responsible for maintaining thousands of topics with overlapping content and producing and maintaining output for multiple audiences are kind of cynical about the value of hiding the complexity; it’s lurking underneath the covers anyway, since authors inevitably become responsible for the implicit context and future of what they write. (This is why I, personally, roll my eyes a little about the idea that DITA “frees writers up to just write”: as soon as you write something you’re making some tradeoffs about, for example, how audience-friendly versus future-proof and reusable it is. That means you probably have to know something about what’s going to happen to your text after you write it, whether you are yourself tagging any topic references or running filters against it, or not.)

—Tom Johnson alleged that developers don’t like XML and this led to a long digression about what developers will and won’t do when providing content, and whether this is any kind of blocker to developers’ creating documentation. There was some consensus that large repositories of developer-created content probably won’t end up being created in DITA (unless there is some kind of form-based interface intervening) but some attendees had had good experiences working with developers who wanted to single-source UI text and documentation text and saw XML as a logical choice for UIs to consume.

–Attendees had some useful responses to the allegations that a CCMS can replace DITA itself: when you do that, you’re back in the world of help authoring tools because insofar as the logic of the CCMS overrides the logic of DITA, you’re going to end up with functionality that is not portable once you take your content out of that CMS. For example,  if you rely on the conditional processing of your CMS for filtered output, you will have to recreate that tagging in your DITA source if you start over in a different CMS. This creates the kinds of uncomfortable relationships with tool vendors that we have talked about before, where there is a cost to moving away from a tool, or you’re waiting on bug fixes to the tool to solve your problems. (I think I have that right. We use SVN and have never used a CMS.)

–There were many tacos. So many tacos.

As usual, it was a great and collegial discussion. Thanks to everyone who participated!



March Meeting: Defending DITA

Our next DITA meeting will be Wednesday, March 16th from 6:30-8:00. As usual we’ll provide some beer and dinner (please try and RSVP if you’re coming).

Instead of a presentation, our March DITA meetup will feature a discussion on the subject of “Defending DITA”. DITA gets a lot of shade from various quarters: some writers think it’s too techy. Developers think it’s too complicated when there are tools like Markdown. And at last year’s Tekom conference, some German CCMS vendors claimed it was entirely unnecessary if you already have a CCMS.

Here are a few articles I’ve been reading to get you started, but if you’d rather, bring your own examples of how you’ve heard DITA attacked and how you responded. Are some of these critiques legitimate? What isn’t DITA good for, and how will you answer if you’re asked to explain why it is right for your use cases (IF it is)?

Two articles blogger Tom Johnson wrote comparing DITA to Jekyll and other developer tools:

An article Scriptorium DITA consultancy founder Sarah O’Keefe wrote about the Tekom dustup:

Eliot Kimber’s response to the same incident:

Let’s use these discussions as a springboard for a satisfying mix of industry gossip and discussion where the value is in DITA today. Hope to see you there!



February PDX DITA Book Club meeting recap: chapters 3 and 4

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

January PDX DITA Book Club meeting recap: chapters 1 and 2

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

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.

October Meetup: Building Faceted Search

On October 28th from 6:30-8:00, please join us and members of the Fiserv technical communications team for dinner, conversation, and an overview of how Fiserv is using DITA metadata to build a site with faceted information search. We’ve struggled with search in our own Help implementations, so this one should be really interesting.

Here is their description:

Join the Fiserv Technical Communications team as they explain how they use metadata embedded in DITA topics for the faceted search features of their online documentation system. They will also present the supporting technology and the process they went through to plan and develop the features.

RSVP to if you can make it.