The trouble began when they changed the documentation tools
Everyone's thinking about new tools -- but why?
To the newly initiated technical writer, it can look like an arms race is underway in documentation tools. Everyone is searching for a tool, or trying out a new tool, or advocating for one.
The focus on tools seems to have two general causes:
Writers are applying for positions that require knowledge of a particular tool or workflow (which implies tools).
Technical writing teams are looking for a tool to solve a multitude of publishing problems or to replace another unsatisfactory tool, so they go shopping.
When the job requires it
Elaine MacDonald, a Boston-area technical writer and editor with more than a decade of experience, is dealing with the first cause. She's in the middle of a job search and plans to spend some time learning how to generate static sites from Markdown, despite the fact that she's already familiar with Madcap Flare, DITA, HTML, and CSS.
MacDonald said she fears that her application could be discarded before a human reads it if she does not find a way to mention Markdown, which numerous positions require.
She wrote that another writer would know ". . .since I know DITA, HTML, and CSS, that Markdown would be a slide on ice for me to use. Auto resume readers would exclude my resume if HR was told to look for Markdown experience."
This week she was doing what many of us have done: Comparing static site generators and thinking about converting parts of her portfolio into a Markdown project.
In search of a tool
Then there's the other scenario, where a team is searching for a tool that will solve all their problems.
Dawn Stevens, a tools consultant for more than 30 years, has seen the situation many times.
The need to solve problems may be real, but the trouble with tool shopping is that most teams are not equipped for it.
Clients have often chosen a tool before they meet with Stevens, seeing the tool as "a magic bullet" that will solve all their problems. Later, they find out that the tool doesn't do what they thought it could do, or that it's difficult to use. "And then the tool gets blamed," she said.
She's seen a few companies change tools as many as three times.
Conclusion
It seems you can find a plethora of misadventure stories about any kind of documentation tool, because no matter how simple, or feature-rich, or robust, or flexible it is -- a documentation team will find a way to misuse it.
Likewise, the “silver bullet” approach leads to job listings that are full of tool names, because writers are expected to hop to the new tool and be productive right away.
The idea behind a series about tools and toolchains was that we'd all be better off with more familiarity of these things:
The layout of the tools landscape. Most tools evolved in a particular environment, and they are best (or most safely) used in that environment. Sometimes tools are especially unsuitable for at least one task or environment. (I’ve always wanted to have a better mental map of the tools available and what they are for, so I went out and asked people who would know.)
The difficulty. It’s not easy to select tools and design technical writing workflows. It can be 100 times harder than anyone expects, and problems can take a lot longer to solve. Wrong moves are easy to make.
Up soon: Why choosing the right tools is difficult.