One of the challenges for organisations moving to a new content management system for their user documentation is selecting an authoring tool that is:
- powerful enough, and
- can be used by non-Technical Authors as well as the professional Technical Authors.
Many organisations want staff, such as developers, to be able to add content to the system directly – without having to pass it over to the Technical Publications department. The difficulty lies in that many tools for authoring in DITA and other XML schemas are daunting to those unfamiliar with the underlying principles of DITA and structured content. It’s even more challenging if you’re someone who is only going to write content occasionally.
One approach is to create templates, with defined fields that need to be filled in. Another is to get staff to write in Word, again in conjunction with a template, import the text into the content management system and then map metadata and other semantic information to the content at that stage.
Is it an unsurmountable problem? Should we just accept that writing semi-structured XHTML content (such as wiki-based content or WordPress-like authoring environments) is a better compromise? What you lose in modularity, you gain in having an easy-to-use authoring environment. Alternatively, do we need to recognize we’ll always need specialists who can convert text into the appropriate format – the equivalent of the typing pool or typesetters?
It has bearing on the role and value of Technical Authors. Is it their main value in writing skills, information management skills, editing skills or in using a specialist tool? If the organisation believes “everyone can write well”, then is their value in using software that’s complex and tricky to use?
“Alternatively, do we need to recognize we’ll always need specialists who can convert text into the appropriate format – the equivalent of the typing pool or typesetters?” – that seems like an expensive alternative, especially in an IT environment getting someone to simply copy, paste & tag content as DITA XML might be considered a resource waste, unless the company is really big & can afford that type of “resource”. I prefer your idea of creating templates & you could create your template as DITA XML in a good XML WYSIWYG editor that has a primitive preview feature so that users who do not want to work with the XML code don’t really need to see it.
No matter how much a DITA editor is made to look like a word processor, it will never ever behave like one if it’s fully featured.
There is a cultural problem as much as anything else: most authors in large companies use Word, have never used anything else, don’t care about anything else, and are immune to anything else. Word is, I think, a kind of mental vampire.
If you can coach authors to write using simple modular Word templates, you perhaps give yourself a change to migrate that text into DITA, without rework. The STOP report is quite a good teaching tool.
There’s no way I’d want someone half-committed to convert Word mush to DITA. If you’re creating a set of interlinked technical content, you want it to be as good as it can reasonably be, so you can get the benefits such as the ability to pop out custom content for people.
The value of DITA is in *reuse*. That’s where you get the ROI. I would argue it’s not really the DITA elements and attributes per se that are so tough… It’s the whole concept of topic-based writing, writing for reuse, identifying and applying candidates for reuse, and conditionalizing effectively.
Even if you give non-technical authors an “easy template” for DITA, how do you make sure they don’t create 10 topics when they should create 1 topic and use it in 10 different publications? How do you train them to take an existing topic and appropriately apply conditional attributes so it can be used somewhere else–rather than just copy and modify it? How do you make sure they insert the appropriate Caution conref into every topic that needs it, rather than just copy and paste it as a plain paragraph multiple times? (Or just leave all the other topics without the critical Caution?) That they apply the appropriate variable element to every instance of the product name, so that when it changes at the last minute, you only have one update to make, not hundreds?
It takes a lot of setup time to reuse effectively. Technical writers develop strong skills here because we’re the ones who face the pain when it’s not done properly: When you’re in trouble for skyrocketing translation costs because you have 20 times the topics you need and lots of language variation. When you’re having to update essentially same paragraph in 25 different topics instead of in just one conref. When that product name changes at the last minute, and you discover you didn’t apply the variable element as thoroughly as you should have. Or that you didn’t conditionalize correctly, and entire key paragraphs are now missing from your publication, and there is a support call escalation at a critical site because of it.
Anyone else, who is just going in “pumping content”, and never has to deal with the ongoing maintenance and output of that content, is never going to do this as effectively. It’s not their job; they don’t have time–they have their own work to do. It’s not about tools and templates; it’s about skill. DITA greatly empowers technical writers to make better use of the skills they already have. It doesn’t magically confer those skills onto other people.