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!

Upcoming Workshop on DITA Authoring

We’re excited to announce that PDX DITA member, information architect, content strategist, Portland State instructor, and general bon vivant Toni Mantych will be teaching a two-day workshop called DITA for Authors on May 9 and 10th, 2014. The workshop is focused on authoring skills, and is aimed at people who already understand the importance of DITA and its value proposition, but don’t yet have extensive hands-on experience in the authoring medium. It will cover basic authoring knowledge like topic types and element use, but also will get into conditional filtering, keyrefs and conrefs and how to get the most value out of your content. Sounds extremely useful!

Full details are here: Dita for Authors

 

 

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.

Problem

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).

Solution

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!

Example

freeimage-6279867-high

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

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

Benefits

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.

Feedback?

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.

Report on March 12th Meeting

Last night’s meeting was almost entirely devoted to discussing conditional filtering, with a few digressions into conrefs, content management systems, and the local taco carts. Melanie Jennings shared her detailed planning process for tagging and filtering a set of DITA files that will currently support six different filtered outputs for different audiences and platforms, but in the future may have to support many more. We also heard about how other PDX DITA members are using conditional filtering in different ways to get the most out of their files, and discussed some of the challenges of ditamap inheritance, enforcing consistent tagging, and, especially, educating all the writers in a group who need to understand not only the tagging model but how and to whom the final output will be delivered.

We were excited to have Toni Mantych join us for the first time. Toni teaches DITA over at Portland State and is planning to teach a DITA workshop in May through the local STC chapter. Stay tuned for more news about that workshop in a future post.

If you’d like to attend the next meeting in June, please check back here for the date or contact us to be added to the email list for reminders.

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!

Opportunity at Jive Software for a Writer with Java/JS Skills

Hi DITA enthusiasts! We have an opportunity working on developer onboarding docs here at Jive Software (the current meeting place of the PDX DITA group): you could be based out of Portland or Palo Alto, reporting to our documentation team but collaborating heavily with our platform API team. If you’re interested, you’re welcome to apply directly via JobVite.

Senior Documentation Engineer at Jive

Anyone who has been to a meeting has probably already raved about our beer, snacks, and view of Powell’s Books! We’re also very modest and charming.

The work for this position will not primarily use DITA, but the rest of the Docs team authors in DITA and you’d almost certainly get the opportunity to use those skills.

A Very DITA Holiday Celebration

Reminding all DITA enthusiasts that PDX DITA’s annual potluck and Year in DITA roundup discussion will take place at Jive Software next Wednesday, December 11th, from 6:30 to 8:00. Make something to share, run by the carts on your way in, or just have a beer and some pretzels on Jive.

We’re hoping to discuss breaking events in DITA world, talk about what we learned at LavaCon, and brag about our conversion to Oxygen Webhelp. What’s up in your world?

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

 

 

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!