Short Descriptions for Tasks

What is a good short description for a task?

Some of the short descriptions indicated as "good" in the class assignments simply restated information that was in the short description of the related concept. The task's short description may have been written differently and in the imperative, but it was redundant information.

If you're looking at a list of short descriptions, like in the parent topic in a CHM output or in a list of search results, you may want to know which topic contain the steps. If the title or short description doesn't say something like "how to" or "follow these steps," users just have to figure out your naming conventions to pick the right topic.

Much of our information will end up in a knowledgebase. If naming conventions are to be meaningful, all KB contributors need to use them. I doubt ours will. They're mostly volunteers, not professional writers or support staff. So we can't count on all content following the same conventions.

Further, pretty much everything we write is translated. Using semantic differences in titles to distinguish different types of topics doesn't always work. I don't know enough of the languages to know if it's simply because that language can't make the distinctions as clearly as English or if the translators weren't consistent or weren't provided with enough instruction.

...in the presentation "Art of the Shortdesc", in the presentations category of the "Resources" area linked above.

Michael Priestley

I looked at the presentation. It has good information, but it doesn't address my specific concerns:

  • If you have a related concept and a task, what do you put in each short description so they're not redundant?
  • If you don't specifically say a topic contains steps, how do you cue users who are looking for step-by-step information via a knowledgebase search? Is it really best practice just to use semantic cues in the title and short description? In my experience, semantic cues get really messed up in translation.

I'm struggling with writing short descriptions for tasks as well. Our organization does not use short descriptions so I'm learning to love them in this class. For our tasks, we use a simple "Use this task to ...." I like the simplicity and the straightforwardness, but it is repetitive and, unless you're careful, tends to mimic the task title.

The presentation that Michael posted has proved useful to me. I'm looking forward to his comments on the next assignment to guide me further. I'm finding that the more complicated the task, the easier it is to write a good short description.

At any rate, this is a great course and I appreciate the effort that Michael is putting into it.

XML.org Focus Areas: BPEL | DITA | ebXML | IDtrust | OpenDocument | SAML | UBL | UDDI
OASIS sites: OASIS | Cover Pages | XML.org | AMQP | CGM Open | eGov | Emergency | IDtrust | LegalXML | Open CSA | OSLC | WS-I