About melanie.jennings

I work at Jive Software with Marya DeVoto and Leona Campbell, using DITA. We have 1500+ topics and a variety of user audiences, versions, and platforms. We support DITA ourselves, so I'm happy to be part of PDX DITA for troubleshooting support and to see what interesting things others are doing with DITA in their organizations.

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.

Getting Started with Filtering

In my last post about filtering, I tried to explain the theory of filtering, so you’d understand which kinds of problems filtering might solve. In this post, I’ll attempt to show how to get started on an actual project. This post is intended for folks who are just getting started with filtering.

Overall Process for a Filtering Project

Generally speaking, I find my process to be something like this:

  1. Create a matrix of the product’s variations and the associated publications so that I have a reference to consult for my sanity. Basically, I’m trying to sketch out which topics I’ll include and how to filter them in or out (in other words, show them or not show them in the final publication). This might be organized by features, audience, revision number, platform, or a combo of any of these.
  2. Use the matrix to define the values I’m going to need in my filter files. A “value” is the definition behind the features, audience, platform, etc. For example, the values might be “beginner,” “intermediate,” or “advanced,” or “Mac,” “Windows,” or “Linux”. Defining the values is basically figuring out who the audience is and the content they’ll need in the publication.
  3. Create the actual filter files (based on the values in the matrix) so that the computer knows how to show or not show tagged topics and inline text appropriately at build/publish time.
  4. Tag the content in the source files for the different features.
  5. Create the final publications (.doc, html, pdf, etc.) using each filter.

Create a Matrix

In my last post, I used the robot product as an example. The robot came in different models, so the matrix I created for that was based on features. But I find that when I change the example, that sometimes produces a different “aha” moment for readers. So this time around, I’m going to use a cookbook example that’s based on audience values (beginner and advanced).

I need to create a cookbook for two culinary school courses: Beginning Baking and Advanced Baking. I’ve determined the chapters I’m going to need and which ones I’ll be able to share between the two different cookbooks. Here’s how it looks:

Define the Values

So in this case, we’re going to need two audience values:

  • Beginner
  • Advanced

Create the Filters

A filter is the actual file in which the values are defined. This may vary depending on which tool you’re using (Frame, Word, DITA, whatever), but the approach is generally the same between tools. As I mentioned in my last post, filtering is largely a mind-shift and less about which tool you’re using to accomplish the goal.

In my shop, we use DITA, so I would create a ditaval file for each of the cookbooks. (The filter files are called “ditavals” because they have a .ditaval filename extension).

  • Beginner
  • Advanced


Note that each of the ditavals includes/excludes the different audience values, like so:

  • Beginner — includes beginner, but excludes advanced.
  • Advanced — includes advanced, but excludes beginner.

The include/exclude action tells the computer which content to include and which to exclude when you publish your guide. So, for example, when you create the Beginner Guide, you want to see the following chapters:

  • Introduction
  • Cookies
  • Cakes and Pies
  • Basic Breads
  • Conclusion

You do not want to see:

  • Advanced Breads
  • French Pastry
  • Croissants

And when you create the Advanced Guide, you want to see:

  • Introduction
  • Cakes and Pies
  • Basic Breads
  • Advanced Breads
  • French Pastry
  • Croissants
  • Conclusion

You do not want to see:

  • Cookies

Tag at the Topic or Chapter Level

So, to accomplish this, you would “tag” the chapters so the computer knows what to show and what not to show at build/publish time. Again, in my shop, we use DITA, so my parent Cookbook file (called a “ditamap”) would look like this:


Breaking that Down

Introduction, Cakes and Pies, Basic Breads, and Conclusion are not tagged. That is because you want these to show (include) in both guides.

Here’s how the guides will look based on the include/exclude information in their associated filter file (the .ditaval):

  • Beginning Guide
    Will include Introduction, Cookies, Cakes and Pies, Basic Breads, Conclusion
    Will exclude Advanced Breads, French Pastry, Croissants
  • Advanced Guide
    Will include Introduction, Cakes and Pies, Basic Breads, Advanced Breads, French Pastry, Croissants, Conclusion
    Will exclude Cookies

If you don’t fully grasp this right now, try not to freak out. You’ll test it! You WILL get this to work. It just takes some time for your mind to adapt to this way of thinking.

Tag at the Inline Level

In addition to the topic-level tagging that you’ve done, you may have some text that you need to tag inline (e.g., specifying “audience=(value)” to specific elements). For example, in your Introduction chapter, you could do something like the following (apologies for crappy image; click it for better readability):


For the xml-phobic, here’s a different view of that same content with some nice red arrows to explain what’s going on (again, click the image for better readability):


Refer back to the “Breaking it Down” section above to understand how this tagged content will show or not show in your different cookbook versions.

QA the Tagging

Here are a few ideas for QAing your tagging:

  • Your tool may have a handy way to validate your tagging. In other words, if you have tagged something incorrectly, your tool may have a way to let you know that and show you exactly where you messed up. In my shop, we use Oxygen, which has a great validator.
  • You can also design in your own quick QA checks. For example, one thing I’ve done in the past is to create a topic that lists the PDF guides. Here’s an example where the table rows are tagged for either “sys_admin” or “end_user” audience value. In the final publication, I can quickly glance at this topic and see if the correct row is showing (in this case, my ditaval filters are such that only the end user row or only the system administrator row should be showing). Here’s how the XML looks:
    Documentation PDFs file in XML

And again for the xml-phobic, here is the same file in the WYSIWYG-ish view. The green indicates content that is tagged:
Documentation PDFs file in WYSIWYG

  • Compare the TOC of the final output against the filter. Is anything showing that shouldn’t be, or vice versa?
  • Look at your build output for any error messages. We’ll explore filtering challenges in another post, but for now, here’s a quick example of a filtering-related error message:
    [FATAL] Failed to parse the input file ‘AdministeringIdeation.ditamap’ because all of its content has been filtered out. Please check the input file ‘AdministeringIdeation.ditamap’ and the ditaval file, and ensure that the input is valid.

Create the Cookbooks

Now that you have tagged everything and you’re ready to create the guides, you’ll push the magic button in whatever tool you’re using (for example, running the build on the command line; running the build in Oxygen; running the build via your CMS, or whatever). In Oxygen, I would choose my filter (e.g., beginning_baking.ditaval), my desired outputs (HTML, PDF, .doc, whatever), and then run the build. I would expect the result to be the Beginning Guide.

Start Small! But Start!

I tried to pick an example that was complicated enough to describe the power of filtering, but still accessible enough that it wasn’t completely overwhelming. My advice would be to pick a small project and practice on it until you get the hang of filtering.

If you have any questions, feel free to ask in the comments. Thanks for reading!

July 23rd Meeting: Keyrefs with Roger Hadley

At our upcoming meeting on July 23rd, Roger Hadley of Grass Valley Software will explain keyrefs in DITA 1.2. You’ll learn what they are, how to use them (with real-world examples), and a few publishing pitfalls to avoid. All DITA experience levels welcome!

As usual, we’ll also do a little meet-and-greet, and enjoy a light meal together. We hope to see you.

Details: Wednesday, July 23, 2014, 6:30 – 8:00 p.m.

Jive Software, 915 SW Stark, Portland

Some Resources for Getting Started with DITA

I’ll be giving a five-minute lightning talk about DITA tomorrow at the Write the Docs meetup at Puppet Labs. Here are some resources for anyone considering using DITA:

Please post your own resources in the comments here so we can all benefit. Looking forward to the meetup tomorrow!

Understanding Filtering

It can be difficult to understand the power of filtering if you’ve never done it before. I’ll attempt here to explain filtering for beginners with plans to write another post about how to actually get started with filtering.


Many times when you’re writing and publishing large amounts of content as a technical, sales, or marketing writer, you need the same snippet or large section of content in several different publications. For example, you use the same Terms & Conditions or Executive Statement in all of your publications (your company website, your brochures, your online help center, and so on).


Rather than writing content over and over again, or keeping it somewhere on your network in a bunch of slightly different versions, filtering allows you to easily reuse content in many different contexts (your company website, your brochures, your online help center). Write it once, use it often. How we do this is called “filtering”. You might also hear it called “single-sourcing” or “conditional text” or some other variation on those themes. Same thing. It means that you, the author, manually “tag” the content for the different versions of the content that you publish. You maintain one version but publish many versions.

To my way of thinking, filtering is really a methodology or way of approaching content and authoring content. Once you grasp the concept of filtering, you can accomplish the actual tasks in many different tools: any number of XML editors using DITA, FrameMaker, or even Microsoft Word.

Generally speaking, filtering is easy to implement. But, we’ll explore more about that in another post. For now, an example!



Let’s say you make a robot product with the following features:

  • Pushes you out of bed
  • Makes your coffee
  • Turns on your computer
  • Checks your email
  • Asks Google what you should do today
  • Makes you a breakfast burrito
  • Drives the kids to school
  • Makes lunch
  • Makes dinner
  • Tells you a bedtime story

And you sell the robot in the following models. I’m going to color-code the shared items for you:

  • The 24/7 Robot
    • Includes all features except Tells you a bedtime story
  • The Morning Robot
    • Pushes you out of bed
    • Makes your coffee
    • Turns on your computer
    • Checks your email
    • Asks Google what you should do today
    • Makes you a breakfast burrito
    • Drives the kids to school
    • Makes lunch
  • The Mid-day Robot
    • Makes your coffee
    • Checks your email
    • Makes lunch
  • The Night Owl Plus Robot
    • Makes lunch
    • Makes dinner
    • Tells you a bedtime story
    • Pushes you out of bed

You need to create long, complex sales proposals, web content, and user guides for all of these versions. Wowsa. You’ll make that happen with content tagging. Read on.


Tagging is the magic behind filtering. Using our robot example, let’s say you have an introductory section that lists all the features of your robot. Rather than maintain four different versions of the introductory section (24/7, Morning Person, Mid-day Person, and Night Owl), you would have ONE version in which the content is tagged for the different models. Like I said, magic.

Once again using our robot example, you would tag your introductory section as follows:

Our fantastic robot will revolutionize your entire life. Here's a list 
of its features: [this content not tagged because you want this text to show 
up in all versions]
  • Pushes you out of bed [tagged 24/7, Morning Person, and 
    Night Owl Plus] 
  • Makes your coffee [tagged 24/7, Morning Person, Mid-day Person]
  • Turns on your computer [tagged 24/7 and Morning Person]
  • Checks your email [tagged 24/7, Morning Person, Mid-day Person]
  • Asks Google what you should do today [tagged 24/7 and 
    Morning Person]
  • Makes you a breakfast burrito [tagged 24/7 and Morning Person]
  • Drives the kids to school [tagged 24/7 and Morning Person]
  • Makes lunch [not tagged because you want this 
    text to show up in all versions]
  • Makes dinner [tagged 24/7 and Night Owl Plus]
  • Tells you a bedtime story [tagged Night Owl Plus]

After you had tagged all the content, you would push a button in whatever tool you use to publish things (again, could be an XML editor, FrameMaker, Word, etc.), and that tool would spit out the version you want to see. More on that in another post.

Version Matrix

I’ve found it helpful to maintain a version matrix for my sanity. The matrix can also be helpful as a reference for other team members. Continuing with our example, the robot’s version matrix would look like this:

Screen Shot 2014-03-04 at 11.30.03 AM


There are many benefits of filtering, but off the top of my head, here are some:

  • Produces reliable content every time. No more “Is this the version I put that improvement in a few weeks ago?”
  • Optimizes your content library. No more maintenance of ten slightly different versions.
  • You can show or not show whole topics, paragraphs, sentences, or a single letter (by tagging it).
  • You can produce many individual publications from one set of content files.
  • Bottom line is actually the bottom line: it saves time/money.

To be clear, the use case or need for filtering is only warranted in an environment in which you are already keeping multiple versions of the same content and using them in a variety of publications.

Start Slowly

As I mentioned earlier, filtering requires a mindset change. It takes some time to fully grasp and implement filtering. Start with one small project. In my next post, I’ll explain how to do that.


Are there posts out there that do a better job of explaining filtering? Please let me know in the comments. Also, any other comments and/or corrections are very welcome.

Filtering Extravaganza!

For our next PDX DITA meeting, we are inviting attendees to bring in and show their filtering madness. Fun, right? If you don’t know what filtering is, this would be a perfect opportunity to pick the brains of local practitioners to see what and how we’re doing with filters.

We’d like to know:

  • How many topics do you have?
  • How many help sets do you deliver from those topics?
  • How many filter attributes do you use for those help sets?
  • What kinds of validation do you use to prevent logic failures?
  • What would you like to do with filters that you can’t do today? Examples encouraged.

As usual, we’ll be meeting at the lovely downtown offices of Jive Software in Portland. We are looking forward to meeting you and talking shop about DITA!

Meet the PDX DITA Folks at LavaCon!

The founders of PDX DITA will be presenting at LavaCon! Come meet us in meatspace!

In our presentation, “Socializing Content Creation,” we’ll talk about the ways we  collaborate on technical content using all the latest social tools in our roles as technical authors at Jive Software. But more importantly, we’ll talk about how you can use social tools to get your work done. Here are the details:

“Socializing Content Creation”

Tuesday, October 22nd, 1:45-2:45

Search and Social Track

Portland Hilton and Executive Tower
921 Southwest 6th Avenue
Portland, OR 97204



DITA-Related Job at Intel

This just in from Benjamin (@WealthOfIdeas). Thank you, Benjamin!


XML/DITA Expert Technical Writer – 708117


The XML/DITA Expert Technical Writer will help conceive, design, and implement documentation for multiple outputs using a single source XML based system. This person will partner with Documentation toolsmiths, writers, developers, and third party vendors to establish an information architecture documentation and implement it in the Mobile Communications Group. This includes converting existing content to a DITA-compliant system using SDL Trisoft, training users on XMetaL, managing meta data and document maps, and working with a vendor to deliver DITA compliant content to a dynamic web based delivery system.


Candidates should possess a Bachelor’s degree in English, Technical Writing, Technical Communications, and Engineering.

Minimum Requirements:
5+ years experience in technical writing, 1+ years managing content for a product, 1+ years of experience working in an XML environment.
– Good understanding of information architecture/information modeling concepts and procedures and familiarity with BUs content – with ability to undertake a BU content audit to define BU content models.
– Good understanding of graphics file types and their appropriate uses.
= Good understanding of Technical Writing principals, including planning, project management, editing and publishing.

Preferred Requirements:
The XML/DITA Expert Technical Writer is an essential role for every program.
The ideal candidate should have the following skills:
Solid understanding of XML, Schemas, and DTDs (creating and editing)
Solid understanding of topic-based authoring and information mapping concepts as they relate to DITA.
Solid understanding of the DITA standard, with knowledge of how the DITA DTDs should be customized and deployed (i.e., specializations, constraints, DITA-OT plug-in creation).
Solid understanding of the DITA Open Toolkit with knowledge of how to customize it (i.e., DITA-OT plug-in creation) to enable new transformation types.
Solid understanding of XPath and XSL (both XSLT and XSL-FO)
Ability to identify and implement corporate trademarking and branding requirements in DITA-OT outputs (PDF, HTML, CHM) using XSL.
Familiarity with ANT build file creation and modification.
Familiarity with XML validators (e.g., Xerces) and XSL processors (e.g., Xalan, Saxon).
Familiarity with XML authoring tools (such as XMetaL and FrameMaker) and ability to customize configuration files (i.e., CSS, CTM and other XMetaL configuration files; read/write rules, structapps files, templates, EDDs and other FrameMaker configuration files)
Familiarity with SDL Trisoft, including file repository structure and access control, Publication Manager and Condition Manager clients, and the Web Client.

Apply at http://www.intel.com

Your Year in DITA (come tell us about it. . .)

Props to Josh from NetApp for last meeting’s amazing breakdown of ant build errors during PDF generation. Wow, we learned a ton, which always makes us want to learn more, of course, so…

In the spirit of the holidays and all those Year in Review, Best of 2012, and other such recaps, we thought it would be fun to hear about your year in DITA. In other words, what did you or your team do with DITA in 2012? Maybe you were just getting started and had to convert several kajillion Frame files. Maybe you got a new content management system that presented all kinds of challenges. Maybe you did something kinda neat with DITA that others could learn from. Let’s do a simple roundtable and hear a little bit from each person. Sound good?

And even more in the spirit, Marya and I will bring some mulled cider and a roast chicken to share. If you want to bring something, awesome, but don’t feel obligated, just come!

Hope to see you! Meeting location and other details are in the right sidebar.

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?