Guest Post by Keith Schengili-Roberts

A note from Noz:

Hi-di-ho, Readerinos!
With the holiday season and some intense projects I’ve not posted in quite a while. In a way I’m still not, in that today’s post comes from my new colleague and peer in the DITA community Keith Schengili-Roberts. I did an interview post prior to the Congility conference on Keith’s well received blog, and I asked Keith to reciprocate. The resulting post below was actually inspired by one of our discussions while working together on some recent client work.


PS – Here’s a reminder of what “NF2” means, if you needed one.


imageIt used to be that editors were much more common in the technical writing business. I have been around long enough to remember people who had “Technical Editor” as their formal job title. Over the years economic and production pressures have forced firms to hire more writers instead of editors. This often results with little or no oversight of existing content, furthering the pressures to silo writers and their content. Content was created, reviewed, and delivered, and rarely looked at again unless a customer raised an issue against a specific piece of content.

When asked, one of the aspects of DITA that most technical writers will agree is important to them is the ability to reuse content. Not just their own, but content that was developed by other writers. Whenever a piece of content is reused, it saves the writer that found it from having to re-write that piece of content. At the same time, the organisation benefits by saving cost, and the user benefits, because reused content makes for more consistent deliverables. I have noticed over the years that one of the other inadvertent bonuses of this approach is that topics that are looked at most – when being evaluated for reuse – become “edited topics” and are improved in the process of reuse. In DITA environments, I am seeing the return of the editorial process as technical writers review and inevitably revise content written by their peers.

Legacy Conversion Can Equal a First Edit Pass to Old Content

While working as an Information Architect I remember running across a classic case of this sort, where a writer had been doing the same manual for years, and took the approach of adding new material he received from the software developer SMEs piece-meal to the existing content. What must have at one time have been a decent manual had become a hodge-podge of barely-comprehensible content, with varying punctuation styles, and different terms (and spellings!) for the same items; inconsistency was the norm rather than the exception. Any editor glancing at this material would have immediately taken out their red pen and set to work (and in fact a section from this original work became a standard editing test for technical writer candidates looking for a job with the organisation).

Since things were so siloed nobody on the writing team had the opportunity to review this work, the hapless end-users had to decipher this deliverable as best they could. In moving this content to DITA the material finally had the chance to be thoroughly edited. Terms were made consistent and the content was cleaned up. Simply converting this legacy content to proper, topic-oriented and info-typed DITA ensured that it would be edited and made consistent, and its content ready to be effectively reused in other end-user content.

Image licensing –

Reused Content Becomes Improved Content

I have seen evidence of content being edited and refined over time, so it becomes more clear and consistent as more eyes are brought to bear on the original versions. I remember another occasion where I was reviewing some end-user content, and I twigged that what I was reading seemed awfully familiar. The CCMS we were using allowed me to locate the topic and discover where else it was being used. It turned out that it was a concept topic that I had originally written for a highly-technical electrical engineering document. I could tell that it had been changed, but ultimately for the better, so that it could work effectively in two very different deliverables intended for two distinct audiences.

As a consultant I am now seeing similar situations at other organisations. It seems to be a natural outcome of the topic writing process when handled within a CCMS with decent search capabilities. This type of behaviour should definitely be encouraged, not only because it is good for the content (and its readers) but because it is good for the writers in several ways.

I find that the better writers on a team are natural editors as well, and allowing them to sink their teeth into someone else’s content means that they get to learn more about that content (and other products/projects) and it also opens up the lines of communication within the team, as would-be-editors ask the original writers about their content, helping to de-silo both the writer and the editor.

Get it? Reuse means looking at content with a fine-toothed comb…

Possible Pitfalls to Be Avoided

When managers see this type of behaviour it needs to be encouraged, but definitely guided. One of the obvious pitfalls when writers-cum-editors run rampant is that they revise material so that it fits their deliverable’s needs but not that of the original deliverable. As long as all of the writers are reminded of DITA best practices – that they need to check content dependencies and to talk to the original writer of the topic when changes go beyond mere grammar corrections/typos – this ought to solve this potential issue before it starts.

The other potential issue that can arise is that a writer may think they are being singled out by a peer and cause friction. There are few writers – myself included – who do not react with some shock when the red pen cuts deeply into their work. In this situation it is good to be able to point to an existing style guide (both for DITA mark-up and for writing generally) so that writer and editor know where they stand.

While many organisations will find it hard to create (or in some cases, reinstate) the technical editor role, having the editorial function emerge in the writing team is a natural outcome when you have good technical writers who are creating topics using a CMS. The best deliverables are those that have had several sets of critical eyes looking at them, and good editing makes for better writers overall.

It’s a win-win-win situation for the writers themselves, the readers of the content, and ultimately for the organisation.


A note from Noz:

To formalise and drive forward the effect that Keith is discussing here, I have even gone so far as formally recommending to clients that they hire dedicated authors to coach and monitor writers. Which is the best way forward depends on the organisation and context, but the impact of reuse on editorial process is a positive trend in all cases.

To learn more about Keith, do check out his blog on