AODC day 2 – Single source publishing
This week I’m attending the 2009 Australasian Online Documentation and Content Conference (AODC) in Melbourne. Today is the second day of the conference.
Here are some notes I took from the session on single source publishing, by Gareth Oakes from global publishing solutions (GPSL). GPSL is a major provider of PTC/Arbortext solutions. I hope these notes are useful to people who couldn’t be at the conference this year. The AODC organisers will also publish the session slides and supplementary material once the conference is over.
Single Source Publishing
This presentation was originally titled “Managing Modular Documentation”. Gareth started with an orientation about the history of publishing, since the days when we were writing on cave walls. Then he discussed the benefits arising from single source publishing, and compared the workflows of traditional publishing versus single source publishing. He illustrated the difference between representational and semantic markup. DITA gives you the framework to start describing the semantic elements of a document.
Gareth’s thesis is:
“The single source approach is now recognised as global best practice.”
He discussed the components of a single source publishing system:
- Authoring — Structured text; photographs and illustrations.
- Publishing — To PDF, help files, web, mobile platforms.
- Content management — Check out/in; version control and the ability to create/store a snapshot; workflow including review/approval; auditing and reporting.
Going into the authoring component in more detail
Unstructured content, such as a Word document, is not suitable for single source documentation. If you’re stuck with unstructured content, you’re not going to see all the benefits of single sourcing. Gareth says that XML is the best environment. It has a solid architecture and a wide support base. DocBook, DITA, S1000D and SCORM are some of the XML standards available.
So an important part of setting up your publishing system would be to design the data model and choose the appropriate XML flavour.
You also need to choose the right authoring tool. Gareth pointed out that some tools are better for different business environments e.g. when your data is highly structured and factual (needs good support for tables) rather than narrative or descriptive. You may need a tool that works well with images, or with mathematical equations. And the tool must work well with your content management system or other technical environment needs.
Talking about the publishing component in more detail
The publishing tool also needs to integrate well with your content management system. It needs to produce the output formats you require (PDF, help, web, etc). Also there may be specific output formatting needed, such as footnotes, rotated text. You may need automatic generation of table of contents, index, etc. Consider the performance side of things, especially if you’re producing large books.
Styling is usually part of the publishing process. You need stylesheets to determine the look and feel of your output. You need a tool that will make it easy to produce the stylesheets that suit your requirements.
Now the content management component (CMS) in more detail
Some people use just a network folder. But a database CMS has more advantages. You need to choose one that suits your business needs and environment, and you must consider whether it’s easy/difficult to set up. It’s better to avoid too much customisation and configuration, because this requires maintenance too.
Gareth listed the basic features of a CMS:
- Check in/out
- Version control
- Searching and metadata — Can you add your own custom metadata, so that the search can recognise them too.
- Access control — You need to control what people can do in your system.
- Reporting and auditing — Useful statistics about the publishing process.
Advanced features a CMS may provide:
- XML support — Only 20% of CMSes support XML natively, particularly compound documents e.g. a book has a number of sections, stored separately. And this is a basic requirement for single sourcing!
- Collaboration — Such as an approval process.
- Publishing services — Gareth likes a CMS where the publishing service sits behind the CMS and you can drive it via simple workflow.
- Auditing and reporting — Many CMSes do basic reporting, but some offer more complex and/or detailed reports.
- Translation management — Managing interactions with the translation service provider. Some tools do this really well.
- Web-based editing tools — Rather than needing a desktop client, the authors can log in to a web site and edit the content that way. Similar to a wiki.
- Digital asset management — for images and illustrations.
- Support for storing CAD models
- Integration between the CMS and the authoring/publishing tools.
Question from the floor: How do you manage links from one topic to another, given that the topics are all held individually and are not visible to each other until published?
Gareth’s answer: Yes, that should be one of the advanced features too i.e. an index of available links and link management — referential integrity.
Looking at release management: You need to be able to make and store snapshots. Then you need to reference objects by release, either the latest one or a specific one. You also need to link the final output (PDF etc) with its source version.
There’s also the question of content branching i.e. when you create a new product, you often need to re-use existing material from the previous version. Do you copy the content or just reference the existing content? You’ll make this decision depending on the circumstances at the time.
Thank you Gareth for a thorough and detailed presentation.
Posted on 21 May 2009, in AODC, technical writing, xml and tagged AODC, DITA, documentation, Gareth Oakes, single, single sourcing, technical documentation, technical writing. Bookmark the permalink. Leave a comment.