Guest Blog: The (very) long road to structured writing

Monday, December 16 2013 @ 11:13 PM, By Maxwell Hoffmann

In this guest blog, respected blogger and thought leader, Ant Davey, describes his personal long road to structured writing. Davey’s experience mirrors the path that many of us have traveled on or are about to embark on. Read on for useful guidance you can apply to your own journey.

________________________________________________

This article is not about the Adobe Technical Communication Suite so much as it is about a (still incomplete) journey. That journey is to get to a point where I can use TCS effectively to produce XML content that can be transformed for delivery in the various formats needed by our audiences.

I work in a medium-sized company which outputs thousands of pages of technical documentation each year. I am the only person who resembles what we might call a technical communicator. About 100 internal SMEs (engineers and railroad operations specialists) and at least that many on external project contracts provide content for publication. The content is almost exclusively produced in Word, and most of our outputs are published as PDFs, with some also going to print.

I originally joined the R&D department, with a remit to improve the quality of our outputs and to introduce single sourcing. It really wasn’t until the whole company moved into one building, about 3 years ago, that I began to see where single sourcing would have any useful payback, through content reuse. And there still wasn’t any motivation or acceptance among the budget holders that there was any need to change things. I knew that, one day, we would need to structure our content to meet the demands of our audiences. [Not customers in the traditional sense, as we are a member-financed not-for-profit.]

We are an knowledge management company

These words, finally spoken by my CEO, brought a glimmer of light to my life. I knew that fewer than 5 people in the company (out of 250) had any idea what this meant. In my own mind I started to debate whether we could be a knowledge management company, or an information management company. We didn’t have definitions laid down for either term. But it was a starting point. Delivering the right information, to the right people, at the right time, [and in the right format (my addition)] had been a company objective since before I joined; finally we might start to do something about it.

One of the first steps was a full review and overhaul of the company website. Except for print, everything we publish was accessed through our website. Its former landing page was little more than a list of links that reflected our departmental structure. (Hopefully, by the time you read this our new website will be up and running – but it’s on Microsoft SharePoint, so no guarantee.) It bore no relation to anything our audiences needed. Unless you had bookmarked the page where the information you needed was published or updated, a search engine was the best way of finding anything.

We went through the appropriate processes: audience analysis, UX, user journeys, graphic and architectural design. I took 6 months out of my day job to create much of the new content. Shorter, more accessible, and easier to navigate, I hope.

Overly long and poorly written

That was one user comment that has stuck with me from the website audience research. I’d been saying for years that we can’t tell people that the piece of information they need is somewhere in one of six 120-page PDFs. We need to deliver far more concise packets of information, targeted to the specific needs of various audiences. And the website research also told us that an increasing number of our audiences are starting to access information on mobile devices, and not just desktop monitors, or printing our PDFs to read on the train as they commute to work. Finally we had the evidence that suggests we need to move towards modular, structured writing.

I had known we would need to do this for some time. When I joined the company at the beginning of 2006, I set out to change our publishing processes. Being scientists and engineers, our ‘content creators’ felt the need to number everything. Not with any great success, as you will know if you have had to work with long Word files. Any consistency I could achieve with new templates usually fell apart when anybody tried to copy and paste ‘Normal +’ content. Normal + is achieved by using the default paragraph style and changing the appearance of text using only in-line formatting.

Moving towards Adobe Technical Communication Suite

I started to use Adobe FrameMaker. I was a novice user, but I knew something of its potential and general acceptance as the tool of choice for the type of document we were publishing. With some outside help I was able to develop a set of FrameMaker templates that included some basic ideas for good information delivery, and a corresponding set of Word templates that my SMEs could use to write their content.

Still no structure as such; still a narrative style of writing. But the templates should get the SMEs used to thinking about applying and working within a pre-determined set of formats when writing their content. The names of the paragraph styles built into the new Word templates were an exact match for those in the corresponding FM templates. Instead of a laborious copy, paste, apply correct formatting workflow, I would be able to open a new (unstructured) FrameMaker file and import the content of the Word file by copying (not by reference). Somewhere in the future it would be easier to transform unstructured, but consistently formatted, content into a structure, and then output it for delivery on many devices and in different formats.

Some 4 years down the line I am now getting people to ask how to use my Word templates, rather than having to force them on people. Providing good, understandable guidance on using your Word templates properly (not Normal +) is essential to a change of behaviour. Captivate has been a useful tool to show how to access the Styles list and to use it, for many Word users.

Somewhere still in the future we will move to a structured authoring environment. I still don’t know what it will look like. But we have much legacy documentation that may need to be published to new formats and for new devices. Using the DITA capabilities of FrameMaker and the power of RoboHelp (see Neil Perlin’s blogs for more about RoboHelp) in a joined-up way, may get us much of the way towards achieving that company objective of delivering the right information, to the right people, at the right time, in the right format.

The argument for moving to structure has become much easier in recent times. As audiences expect to be able to access information on a growing array of mobile devices, the only way to do this effectively, from a single source of content, is by using structured content. As a lone technical communicator in a world of engineering SMEs, Adobe Technical Communication Suite has the potential to help us achieve long-standing company objectives.

About our Guest Blogger, Ant Davey:

DSC_1675-2Originally a marketing and PR copywriter; little did I then know I was already working in technical communication – translating the complex and technical into understandable, unambiguous language. Once I ‘discovered’ technical writing, I knew it was what I should be doing and enrolled on the distance learning MA course in Technical Authorship at Sheffield Hallam. On the strength of doing that course I got my first tech writing job with a large software company. (The CEO has a passing interest in yacht racing.)  I freelanced for a while and then found myself back in a software development environment. This time with a start up specialising in 4GL database  user interfaces. After a couple of years I decided that I needed to work with more than 6 verbs and moved on.

For the last 7 years have been working in the railroad industry, writing, editing, publishing, and trying to persuade engineers and other SMEs that sentences should be short, and its isn’t how much you write that shows how clever you are. Having thought, a few years ago, that I would be happy forever being a top quality ‘back room boy’ I’m now taking a lead and proposing ideas for content management strategy, information development, management, and delivery.

  • Categories

  • Archives

  • Authors

  • Useful Links

  • Recent Comments

    • Don Bridges: I expect privacy concerns will tamper IoT for our homes and consumers, but for business it will usher a...
    • Lois Patterson: I’m always happy to see math support, although I’m not currently using FrameMaker. I have...
    • Olga: I know it’s a really old post but I was unable to find any information online. I need to number the...
    • click: yes. http://wwwimages.adobe.com/www .adobe.com/content/dam/Adobe/e n/volume-licensing/pdfs/avl...
    • tiggyboo: I know the specs say IE 9 or greater is required – but was Server 12 developed specifically for IE or...