We discussed Chapter 6: DITA Maps and Navigation of DITA Best Practices at the March 16th meeting of the PDX DITA Book Club. The book club members provided great insight. Members included DITA enthusiasts from Jive Software, Netapp, Harmonic, and ADP.
Here are the highlights!
We started by talking about information modeling:
- Marya tried to install the IBM Information Architecture Workbench software discussed in the chapter, but it wasn’t compatible with her 64-bit computer. No one at the meeting had experience with it. Have you ever used it? Let us know what you think in the comments!
- When first starting a large project, Josh used a digital sticky-note tool to organize information, and Marya and Leona used actual sticky notes when reorganizing their doc sets a few years ago.
- We all agreed that it is difficult to figure out how to use modeling tools when you inherit docs or are in the middle of a project. For a team starting out fresh, information modeling seems crucial, whether you use software or sticky notes (or sticky-note software).
We were introduced to new tags and elements by our fellow book club members:
- Josh introduced us to the “resource-only” tag. You can tag a topicref as “resource-only” when you want to refer to a topic from another ditamap but don’t want the topic pulled into your current ditamap.
- Toni introduced us to the <topichead> element. If you want a heading in your TOC but don’t want to create a topic just to get it in there, you can add a <topichead> to a ditamap. This reduces the need for one-sentence summary topics created only to get a heading into your TOC. However, <topichead> does not generate a landing page with mini-TOC grabbed from topic titles and short descriptions, so you’ll need to weigh your need for a mini-TOC against your need for a topic-less heading.
We discussed ditamap ownership:
- Whether or not a team has someone responsible for creating the structure of its ditamaps depends largely on the size of the team.
- A small team can spread ditamap ownership over the whole team, allowing all team members to get involved. This is a joy to some on small teams, and it is also a necessity.
- A large team needs ditamap owners for consistency across the team.
- Josh’s team has Book Captains who are responsible for the published book at the end of a project and for the ditamap structure at the beginning of it.
We considered good use cases for submaps:
- Submaps make reusing maps easy. Content reuse at its best!
- We also really like the mini-TOCs that are automatically created when using submaps.
- Kate creates ditamap templates for her teammates, complete with recommended submaps, for consistency across her team.
We figured out who uses bookmaps (and who doesn’t):
- This chapter of the book advocated creating a bookmap for PDF output and a ditamap for other outputs. Since bookmaps can handle other outputs than PDF, and since ditamaps can handle PDF output, the group didn’t think it was necessary.
- Tech writers for hardware docs tend to use bookmaps, because their readers rely on PDF output and may be in a place where there isn’t internet or a computer nearby.
- Tech writers for software docs tend to stick with ditamaps, but most of the software tech writers present still made PDFs available from their ditamaps.
Couldn’t make it to the meeting but have something to add? Do you want to weigh in on bookmaps and submaps? 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: April 20, 2016 from 5:00 to 6:00 pm
What: Chapter 7 of DITA Best Practices
RSVP: Email email@example.com