We discussed chapter 10: Content Reuse of DITA Best Practices at the August 24th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Jive Software, NetApp, Intel, Viewpoint, and DITA Strategies.

This chapter discussed the benefits of content reuse and single-sourcing as well as covering specifics of how you can do it with DITA. Our conversation on this chapter centered on how to think strategically about content reuse and DITA.

Conref source files
Our members have a bunch of great names for the topics that house content they plan to reuse in conrefs: master reuse files, conref libraries, warehouse topics. No matter what you call them, remember to set the processing-role attribute to resource-only and keep them in a place where you can find them easily.

Keys
Amber gave us a great overview of keys. Keys do for reuse what reltables do for links by storing information outside of topics, making it easier to find and update. Just like linking behavior is stored in reltables but resolve in topics, key values are defined in maps and resolve in topics.

Advice for content reuse
Make sure you always have a good reason why you want to reuse something. The ability to reuse is not a reason to reuse. When in doubt, don’t do it.

Start talking about content reuse strategy with your team, and keep talking about it. Amber suggested setting up brown bags where you and your team rewrite a topic together, talking about what to reuse and what not to. Josh has regular topic reviews with his team. I’m looking forward to scheduling something like it with my team soon.

Couldn’t make it to the meeting but have something to add? How does your team reuse content? Discuss in the comments!

More people are coming to every meeting! You should join us for the next PDX DITA Book Club meeting:
Where: TBD
When: September 28, 2016 from 5:00 to 6:00 pm
What: Chapter 11 of DITA Best Practices
RSVP: Email canncrochet@gmail.com

We discussed chapter 8: Metadata and chapter 9: Conditional Processing of DITA Best Practices at the June 22nd meeting of the PDX DITA Book Club. Attendees included a new member from Viewpoint and DITA enthusiasts from Jive Software, NetApp, and Daimler.

These two chapters were a perfect pair to discuss together. Our group members had great tips for using metadata and conditional processing and plenty of examples of how they use them day-to-day.

• If you have a long topic, instead of putting all of your <indexterm> elements in the <prolog>, you can put them nearer to the information that the index entry is describing to make that information easier to find.
• Set the translate attribute to “no” for items that shouldn’t be translated or that will cause issues with translation services. Our members have used this for superscripts, part numbers, and button UI text that shouldn’t be translated.
• Stan Rhodes made a great point about publication dates and the <prolog> element. It’s possible that the publication dates you use internally for a topic are not the same as the dates you want to use in your published topic. Consider whether the publication date you use in the <prolog> element is the one you want associated with your published topic.
• Even though you can add conditional processing attributes to rel tables and inside topics, most of the group members preferred to add them to the <topicref>, if possible. It’s easier to find them and keep track of them that way.
• We discussed whether or not any members dealt with condition sprawl, a term coined by the book writers to describe when a team has multiple conditions for the same purpose. We all agreed that condition sprawl would probably be more of a problem in large teams than in small teams, which was the perfect segue to PDX DITA quarterly meeting that followed!

Couldn’t make it to the meeting but have something to add? How does your team use metadata? 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: August 24, 2016 from 5:00 to 6:00 pm
What: Chapter 10 of DITA Best Practices
RSVP: Email docs@jivesoftware.com

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!

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 docs@jivesoftware.com

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!

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 docs@jivesoftware.com

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!

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