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

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

  1. Thanks for organizing this book club Christy! This is a great opportunity for all levels of DITA expertise. By walking through this book two chapters at a time, we are able to visit (or revisit) the fundamentals of DITA. Even for someone who has been working with DITA for over 10years I know I have missed some basic understandings due to just needing to ‘get it built and out the door’.

    Looking forward to the next meeting!

Leave a Reply

Your email address will not be published. Required fields are marked *