About Marya DeVoto

Documentarian and DITA evangelist at AppNexus, a Xandr company; formerly Documentation Manager at Jive Software. Interested in practical and impractical information schemes, the social Internet, peace, love, understanding and dactylic hexameters.

Documentation Pipeline: The Awkward Teenage Years

At our August 14 meetup, we’re excited to hear from Josh Johnson of MapR Technologies, who will be speaking about “The Documentation Pipeline: The Awkward Teenage Years.” Josh is a DITA tools developer with 15+ years experience enabling tech doc and content management teams to provide state-of-the art content creation and delivery. Ask him your questions about how he’s supported doc teams in evolving their DITA implementations from simply up-and-running builds to highly efficient systems that support key performance goals.

The usuals are as usual: 

  • Meetup from 6:30-8:00 PM Pacific Time on 8/14, with the talk beginning at 7:00
  • There will be food, and drinks in moderation!
  • The location is AppNexus/Xandr headquarters, in downtown Portland, OR at 711 SW Alder Street, 4th floor. The building is also known as the Alderway Building.
  • Please RSVP to marya.devoto@xandr.com if you plan to come in person–or if you’d like a call-in option. We always plan veg options, but can handle other requests with advance notice.

Hope to see you there!

Reviving PDX DITA – And a Meetup

This post is to announce we will be resuming quarterly meetings of our PDX DITA user group, which has been a bit sleepy the last couple of years. We’ll kick this effort off with a meetup for old and new DITA practitioners and friends on March 6th from 5:30-7:00 PM at AppNexus, 711 SW Alder Street, Portland. Bring yourself, your DITA-curious friends, and your opinions. We’ll talk about our current DITA successes and problems, and discuss ideas for future meetings. A more formal session will follow in April.

Many thanks to Puppet for hosting a number of meetings while the group didn’t have a home office. With my employer, AppNexus, beginning a big DITA migration, it seems like the perfect time to re-launch in a new location.

To review details:

March 6th, 2019, from 5:30-7.
AppNexus (a Xandr company)
711 SW Alder Street, Portland, Suite 400

As always, we’ll have snacks and drinks! Come say hi to old and new friends in that inimitable open-source way. Contact Marya at marya.devoto@xandr.com if you have questions.


Quarterly Meeting with Bonus Puppet Migration Talk

At our last meeting during the DITA Adoption Committee listening session, Puppet representatives shared some early details from their ongoing DITA migration project. During our meeting on the 28th of June, they’ll be presenting on “What We’re Learning: Midway Through Puppet’s DITA Migration.”

From Michelle Fredette, Puppet’s documentation manager:

Puppet writers talk about their migration from markdown files stored in GitHub and published to a static site, to DITA files managed in easyDITA and published to the company’s Drupal site. We’ll talk about the long slow march and decisions we’ve made to convert hundreds of files, design our architecture, train the team, and create a new publishing pipeline.

Food and chatter start at 5:45 at Puppet’s offices (308 SW 2nd Ave, Portland), with the presentation starting at 6:00. This will also be our quarterly meeting.

To RSVP, please email maryaed@gmail.com.

DITA TC Listening Session Report

On March 8, Amber Swope and Nancy Harrison of the DITA Adoption Technical Committee met with local DITA practitioners to listen to stories, suggestions, and complaints in reference to their individual journeys of DITA adoption. In attendance were representatives from FiServ, NetApp, Daimler, Viewpoint, and other local companies, and also Keith Schengili-Roberts, Scott Hudson, and Stan Doherty of the DATC.

The Technical Committee was particularly interested in gaps in the DITA specification that could be filled in for the next release. However, the discussion was wide-ranging, including the challenges of SME authoring in DITA, the need to constrain elements for new DITA writers to ease the learning curve, and the restructuring of existing content required before migration. We learned that the Lightweight DITA Committee is making progress on Markdown-to-DITA authoring; most attendees registered their recommendation for the Git flavor of Markdown as the most useful one.

If you missed this session and want to share your opinions, listening sessions will be ongoing, including one that will take place at the DITA North America conference in San Diego on April 25th. You can learn about more upcoming sessions as they’re scheduled at https://wiki.oasis-open.org/dita-adoption/listeningsessions.

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!



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 marya.devoto@jivesoftware.com if you can make it.

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.












March Meeting: Reporting on the State of DITA

The highlight of last night’s meeting of the PDX DITA User’s Group was Keith Schengili-Roberts’ presentation on The State of DITA 2015. Using the crude metric of “more people to feed at our meetings” over the last few years, we had observed that interest in DITA is growing, but Keith provided a more expansive view of the subject based on his research from the last decade. Here is a sampling of data-based observations drawn from his analysis of job postings, case studies, presentations, LinkedIn references and individual reports:

  • Many hundreds of companies worldwide use DITA, with a concentration in the United States and specifically in California.
  • Computer software might still be the largest individual industry using DITA, but a large array of industries outside software make up the lion’s share of users.
  • DITA is the dominant flavor of XML cited in technical writer job postings (DocBook appears rarely these days)
  • In United States job postings, demand for XML experience is trending up and demand for traditional tech writer tools that don’t require structured authoring is gradually trending down.
  • DITA experience is increasingly required or preferred in job descriptions.
  • Job postings asking for DITA expertise are offering higher starting salaries on average than job postings requiring FrameMaker expertise.

The Q&A covered DITA and aerospace standards, demand in the DITA-based CMS market, how review processes work in a DITA-based documentation organization, and how to get better PDFs out of DITA. And Mark Giffin, who called in from California (he is on the OASIS Lightweight DITA committee), alerted us to the existence of an open-source Markdown-to-DITA plugin. This should be of interest to DITA users who work with programmers who see DITA as an obstacle to collaboration.

Thanks to Keith for providing such a great and engaging talk! You can read more about Keith’s work at his blog, Ditawriter.com. Keith’s presentation was sponsored by Ixiasoft who happen to be his employer as well as a maker of DITA component content management systems. (Thanks to Leah d’Emilio for setting up the tech side and making sure everything went smoothly.)

We were especially pleased to see a handful of new DITA users turning up to explore and network: if you’ve been dithering about coming to a meetup because you’re not yet using DITA, please consider this an invitation to show up and find out more. Also, we discovered proudly that one of our regular attendees found a new job by networking at one of our meetings! We like to be socially useful as well as charming so this was very gratifying news. Maybe you will be next.