Knowing the requirements first prevents toolchain misery later
Documentation tools have to fit the circumstances where they're being used, and every company's circumstances are unique.
I talked with a handful of tools experts over a month or so about selecting tools and toolchains, and this seemed to be a take-away that experts of all stripes can agree upon.
Technical Publishing Consultant Alan Houser summed it up well. "Every situation is different," he said. "Every organization has different constraints and different goals and different requirements and different culture."
When all those factors are added together, they point to a specific combination of tools and processes for that organization.
It's never the tool's fault
There are myriad ways that companies can end up with the wrong tool for the job.
Sometimes people are sticking with what's familiar, even when it no longer fits what they are doing, said Liz Fraley, CEO at Single-Sourcing Solutions. "People recommend and want to go back to what they're comfortable with."
Other times people want a silver bullet.
Dawn Stevens, president and owner of the consulting firm Comtech Services said, "I think it's the most common problem. People expect a tool to be the magic silver bullet, right? They believe that new tools will make the documentation better, and they don't change anything else."
But the same content and the same old processes combined with a new tool add up to a difficult experience for the writers, she said – and then the tool gets blamed.
Along the same lines, Houser said: "A lot of people have the idea that if we choose the right tool it will make a difference, sort of like an amateur photographer thinking, 'Oh if I just buy this high-end camera my photos will be great.' It doesn't work that way."
Sometimes people are using what they think everyone else is using. (This is my favorite theory because I've been one of the technical writers wondering which tools I should learn to keep up with everyone else.)
Lastly, Fraley cautions against vanity projects that are undertaken to pump up a team member’s resume with implementation of a new tool. "Don't do projects that are about one person moving on," she said.
First: Don't be in a hurry to change tools
If you have a tool that nobody seems to like, go on a search for answers before trying to switch to a shiny new tool. Find out whether the old tool was selected for a reason. Ask what cause you have for getting rid of the tool. (Is it only so the writers can try something new?)
You might find that the toolchain you have can produce your documentation just fine, or that changing to your writers' preferred tool doesn't solve the problem.
Stevens cautions that she's worked with "a lot of customers" who have changed their CMS system as many as three times. "Because they bought the fancy shiny thing, and then when they went to use it themselves they didn't get the results they expected."
The experts seemed to agree that if the tools you already have are getting the documentation published, then they're fine, even if you're not using the coolest new tool. That's true because the most important factors in choosing a tool have to do with whether the tool fits your needs.
"Your tools are okay if they fit your situation," Fraley said.
Second: Write out the requirements
If you really need to search for the right tool, the best thing to do is carefully consider the needs of the organization and audience, and then document the requirements.
Samuel Wright is a specialist in docs-as-code workflows who formerly worked with automated DITA pipelines. (He's known as plaindocs in the Write The Docs GitHub repo.)
"What are you trying to do?" Wright asked. "And what tools and what team do you have in place to do it?” If nothing is in place, "pick your poison," he said. He cautioned that for writers without coding skills and without engineering support, a docs-as-code approach will be a tough way to go, especially if the site will include thousands of pages of docs, and API integrations, and search. On the other hand, he knows how hard it can be to work with the wrong tools when a docs-as-code approach would have been better. He once had to a document a C++ codebase using MS Word, which was not ideal for that project. "I've wouldn't wish it on anybody," he said.
Fraley said she's been trying to get her clients to write requirements for more than 25 years, although not always with success. Her first question is always "Why new tools?" She wants to know what assumptions are built into the decision. She keeps asking why in order to understand what the goal is.
Dawn Stevens also likes for her clients to document requirements, but no more than a quarter of her clients actually do that. "More often than not," she said, "they come in and say 'We've already chosen this tool. Tell us what we can do.'"
When Stevens can get clients to think about their requirements, she asks them to consider the needs of not only the end users but of the authors and reviewers.
Houser starts with the three issues that carry the most weight in the decision:
How much content do you have?
How many writers contribute?
What formats do you need to publish in?
He said it’s usually necessary to dig before you get down to the real requirements.
"Is this requirement a real business or customer requirement, or a requirement because we've always done it this way?" he asked.
He explained that real requirements are actually not hard to identify. "Does this choice or action or requirement make your customer successful?" he asked. "Does it improve their understanding of your content? Does it improve searchability? Does it improve the customer experience of your product?"
Both Fraley and Houser said teams can write their own requirements without hiring a consultant. If they do, they should talk to all their stakeholders, Houser added.
Once you document the requirements and know what you're looking for, Fraley said, the tool is always obvious.
_ _ _
Sources:
Liz Fraley, interviews June 30 & August 8, 2022
Dawn Stevens, interview August 19, 2022
Alan Houser, interview August 4, 2022
Swapnil Ogale, interview August 23, 2022
Samuel Wright, interview August 23, 2022