We discussed Chapter 5: Short Descriptions of DITA Best Practices at the May 18th meeting of the PDX DITA Book Club. Attendees included DITA enthusiasts from Jive Software, NetApp, Daimler, and PSU’s Technical Writing program.
Personally, my favorite thing about short descriptions is the way they show up in mini-TOCs. I love being able to easily view a summary of the information in a set of topics. It helps me organize my information, and it helps readers know what to expect, too.
While it seems like there isn’t much we could add to the illuminating and in-depth presentation and blog post that Marya DeVoto did on short descriptions, here are some highlights from the meeting!
- A helpful short description could make it so that an advanced user wouldn’t even have to read the topic.
- To a similar point, sometimes the short description IS the whole topic, and that’s okay.
- Short descriptions should be readable on their own. Avoid introducing lists in a short description, and refer to other topics by name instead of by “previous topic” or “next topic.”
- Being consistent in applying short descriptions helps search results.
Some great final advice from Marya–if your topics are well-structured, your short descriptions should be easy to write. If you are having difficulty writing it, take a second look at your topic and make sure it contains only one point or task.
Couldn’t make it to the meeting but have something to add? What’s your favorite thing about short descriptions? 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: June 22, 2016 from 5:00 to 6:00 pm
What: Chapter 8 and 9 of DITA Best Practices
RSVP: Email docs@jivesoftware.com