November 2005 | IT Week (print edition)

Publish and don't be damned

Publishing electronic documents inside organisations sounds easy, but demands both ingenuity and heroism.

To Warwick, for the eighth annual conference of technical publications managers, organised by translators ITR. I expect controversies on IKEA instruction manuals, but the proceedings are much more corporate than that.

Neil Johns leads a seven-strong team at CSR, a City-quoted specialist in the design of single-chip devices for Bluetooth and Wifi. Over multiple global sites, product lines, contributors and reviewers, he used to have the job of taking product briefs, datasheets and data books, written in different styles of Microsoft Word, and turning them into pdfs. He had no ‘single source’ way of publishing - no way of making a modification centrally that would affect all users. US users, in particular, ignored templates and styles, and sent back documents in such a state, re-styling them took a whole day.

Johns explains why he elected to go over to XML mark-up language. It now allows him to translate into lots of nations’ languages, organise single source, control versions, take direct data inputs from R&D, output documents in a variety of formats, and tailor templates to particular customers. His advice? XPath is very useful for search routines. Don’t be afraid to override precedent, and even Word itself (for example, in how you treat footnotes). Do think about if and how you can recruit the kind of staff to deal with all this.

From ITR, Sally Haywood echoes Johns in upholding XML as a means of separating form from content. She also notes that Adobe’s FrameMaker doesn’t handle Arabic or Thai, just as Quark’s QuarkXPress doesn’t do Japanese or Chinese. Adobe’s InDesign, by contrast, speaks all these tongues.

From consultants Cherryleaf, Ellis Pratt also brings wisdom - indeed, he has lessons on metrics that go beyond their use in technical publishing . First, he rightly issues what he calls ‘18 minutes of health and safety warnings’ on how to measure - and mainly how not to measure - productivity. The point, he says, is that you don’t want to be having conversations with management about page count, cost per word, or number of pages put out per writer.

That will put you on a treadmill of ever-more-painful cost cutting. Better to frame your metrics in terms of your company’s strategic objectives.

Pratt’s recommended range of metrics to run - from between nine and 16 - seems too high, for my money. Nevertheless, he reveals much in citing web content guru Saul Carliner about what kind of levels of productivity you might expect from individuals in the documentation department: about two hard-copy pages, or three or four online screens, a day. And the savings that derive from single source publishing? IBM says 80 per cent, but Pratt suggests that JoAnn Hackos, another content management guru, is nearer the mark with a figure of 30 per cent.

Last, from illustration specialists ITEDO, David Manock shows us how to label diagrams with call-outs (mini captions, to journalists like me) and hot-spots (interactive details). Htat’s fun; but in speaking of the need to integrate illustrated documents with 3D CAD information, Manock underlines the wider rationale for single source publishing.

With departmental company ‘silos’ still in force, those in charge of technical information are usually at the sharp end of any drive to pull a firm together. They are not so much a cost, more the unloved mirror to today’s loss of corporate cohesion. They deserve investment, not beating up.