One of the refrains you’ll hear over and over (and over) again about structured authoring is that topics should be short.
Here’s a frequently held conversation about this guideline:
Writer: How short?
Structured Authoring Guru: Long enough to convey the necessary information, and short enough to be really focused. You know, modular and nimble and reusable.
Writer: Okay. Makes sense. So, like, a couple paragraphs?
SAG: It can be less. Or more. It has to have all of the information that pertains. But no “nice-to-have” information. That stuff goes into its own topic.
Writer: Ah. So the maximum limit is … one paragraph? Or, like, four paragraphs?
SAG: If that’s what it takes. There’s no real set limit. Blah blah long enough blah blah short enough.
Writer: Got it. <quietly quits job, moves to country to keep bees>
Is it ever okay for a task topic to have 47 steps?
I had this conversation with a technical documentation team just recently. This team is well-versed in the traditions of the DITA XML standard. They know that the general guideline for tasks is to keep to about 12 steps, maximum.
Any longer than 12 steps, your structured authoring guru will tell you, and you reduce your opportunities for content reuse. You also risk making your users lose their place.
The team took the DITA best practices to heart. They invested time and energy into revising their extremely long implementation procedures. These procedures involved multiple pieces of hardware, several different software applications, and several setup screens.
There were logical places to separate this content into topics. They gave each new topic a descriptive title, They included a prerequisites element to help connect each task to the one before it and ensure the user had everything they needed for the task. They also included a post-requisite element to guide the user to the next task (in addition to placing the task topics in a specific sequence in the document).
And then their field technicians hated it. They pushed back. They said, not quite in these exact words:
- Why do I have to do so many tasks when really it’s just one procedure?
- It’s too hard to figure out how to go from task to task.
- We’re losing our place, there are all these tasks!
Criteria for deciding whether to allow a long task
“Best practices” should never interfere with the practical application of the content. However, you shouldn’t abandon the best practices on an ad-hoc basis, either.
The solution is to develop criteria so that writers know when to do something differently. We often work with our customers to develop content models and structured authoring guidelines that address not just their usual types of content, but special situations as well.
Here are some examples of criteria for when your team might allow a task topic to go on, and on, and on.
- The task does not have any reuse potential at all.
- The task will not be included in outputs where a long series of steps would be extremely difficult to follow, such as a slide deck, a customer support email, or a chatbot response.
- There’s no “task within a task” or “small goal within the larger goal” that would logically allow for chunking the steps into individual topics.
- The long task does not include a large volume of substeps, notes, or branching of different options, all of which make it harder to see where the next step is.
- The users have demonstrably struggled with small tasks assembled into a complex procedure but have shown success with an “infinite scroll” model of dozens of steps.
If you’ve worked with DITA for a while, you probably know just how rare it is that a task would meet all of these requirements.
Rare, but not impossible.
So, 47 steps?
Yes. You can have a task topic with 47 steps. But you better have a really good reason for it.
The exact criteria you develop depends on your resources, your content, and your customers. Your teams need to know exactly when to follow DITA best practices and when to break them with intention. Your content models should account for exception cases as well.
Ultimately, my tech writer friends had to put their task content back into long topics for their field techs. What they learned from that experience is now guiding them as they develop a new set of structured authoring guidelines that go beyond the basics of DITA best practices. The result is that even the exceptions are becoming more consistent and unified over time.
It might be a long task. But now, no matter which writer created it or which writer modified it, it’s a consistent, structured, usable task that meets the target audience’s needs.
- The Triage Triangle: Solving Complex Content Problems - August 28, 2024
- Get More Value from Less Content - May 20, 2024
- How to Tailor Structured Content Strategy in Pharma and Biotech - March 26, 2024
