Why am I scared every time I hear or read about “easy” or “light” tools and standards for tech writers? Do we really need to scream out for compassion? Is technical writing that complicated?
Assuming that tools are complex and distract us from the main task, meaning actual writing: How should we see our job? From what I see around and on the Web, the message seems to be: “I’m a writer, I have an English degree, so I just have to be creative, write freely, without restrictions from standards or tools.”
Reality check: The customer is paying for an immediate solution to a problem, not for reading our best essay. The employers pay us to deliver accurate, readable, findable, and timely information. So, setting aside that creative writing is not necessarily informative, we are required to work by certain standards and with discipline. We have to contribute to the business objectives, not to the national literary patrimony… at least not during business hours.
As for the tools or code, why wouldn’t we prefer writing some XML tags to apply semantic structure to the information, instead of pressing some buttons to apply just styles and then spending more time on tweaking the layout than we did on writing the text?
If the target users and the business model need to find and exchange the content on various devices, so be it. We can support them.
Instead of writing in a word processor “Place the cup on the tray and press Coffee“, then selecting “Coffee” and applying some style from a list, we can just as easy, or maybe even quicker, write in a plain text or wiki editor “Place the cup on the tray and press *Coffee*“.
Even better, in a text or XML editor, we would write: “Place the cup on the tray and press <uicontrol>Coffee</uicontrol>.” Now Coffee has semantic meaning, and can be rendered in whatever way the customer needs it. Might be bold, might be brown, might even be hot and smell like coffee, why not?
And why should we be scared, if we’d have to write “Place the cup on the tray and press <uicontrol keyref="btn_hotbeverage">.” so it can be reused by colleagues, by business partners, or even by the entire community, if we’re acting in the crowd-source spirit of the Internet (of people and things)?
One small step for man…
Think DITA 
I think the argument for simplicity centers more on collaboration with non-writers than anything else. It’s fine for the tech writer to add tags, but would you expect a product manager or other contributer to tag everything with dita markup as well?
Hi Tom, I totally agree we should look after a good relationship with our collaborators. My post is addressed to writers, because the “non-writers” I collaborated with so far accepted structure and modularization quicker than I thought.
Of course I do not expect them to master DITA language, but especially engineers and developers are easier convinced than writers by the advantages XML brings. Once collaborators understand we’re on the same side and our mutual goal is to support the users with findable, accurate, easy to manage information, XML is accepted as common language.
In my opinion, it should be clear though, that “non-writers” are collaborators and reviewers, so we cannot expect, nor allow them to do our job. I’m happy as long as they accept to draft simple texts in XML, in whatever environment we can share. It is our job as technical communicators to do our research, to process the drafts, to do the writing and to craft the final information for the users, and frankly, I still see some resistance there, on the writers’ side. It’s a pity to blame XML for it.
I was thinking about your post again. I do think that it’s tempting for companies to put in place simple documentation techniques at the start, when their documentation is minimal. As the months go by and the documentation grows, it gets harder and harder to shift gears to another process. After a few years, there’s a ton of content, and if the simple process involved non-structured content, it’s a total mess to manage. So maybe the best strategy is to begin with a more robust solution even if your initial requirements are simple.
For example, at my current company, I’m sure the first doc requirements were simple. Maybe 25 pages? Someone created a Drupal site, activated the book module, and bam, there was a fresh-looking documentation set. Now there’s a lot more content, maybe 500 pages, and it’s much more complicated, with different versions, audiences, and even legacy versus non-legacy features within the same versions.
It would be nice to move to an XML structure in order to better manage it, but it’s all trapped in Drupal and converting legacy content is a major endeavor. Plus, many enhancements and import mechanisms have been added to Drupal, making the company more invested in making this simple solution work. It would have been so much easier if the doc started out in the right way. Then years later, when we decide to do something different with it, the conversion wouldn’t some massive undertaking.
Problem is, the first tech writer wasn’t a tech writer. It was someone playing a tech writer’s role. Usually the tech writer is brought on when the problem is sufficiently complex that the initial person can no longer handle or manage it all.
Tom, thanks for sharing your experience. I have to say, I admire your courage in dealing with that legacy project.
As far as I can see, your story touches some crucial aspects to the fate of techcomm in an organization: handling content as a business asset, even in its incipient state, and putting the writing job into perspective. Content is alive, it evolves along the product lifecycle, so if the business takes the design of its products seriously, it should also plan for a documentation process that can grow with the product development. And it does not necessarily mean an increase in page numbers, but mainly in what the environment, the authoring and publishing technology will have to support.
You identified some causes, namely the ad-hoc beginnings and the patching work in your legacy project, but I hope you get the chance to present the effects of that process to your management and make the case for structured work. They’re lucky to have a motivated writer on their side this time.