A client invested a billion euros but forgot to commission documents. After somehow operating for 18 months, they called me in to sort out the situation, starting (this is true) with a shoebox of incomplete, unlabelled USB sticks kept in a cupboard.

With expired subcontractor warranties and barely any useful data, I used a variety of skills and tactics over an extended period, to elicit data, layout drawings, O&M manuals, safety certificates etc from fifteen unwilling external providers.

I worked with engineers to determine what we had, didn't have; what was inaccurate, incomplete, obsolete, irrelevant, missing. From there, we built a map and started on the long journey to a solution.

The 100,000 verified documents that formed the backbone of a living data library when I left them are still in use and under ongoing revision as needed, seven years later.

Often, a simple review and approval chain, marked off with a change log in the relevant page or document is enough.

Sometimes more detail is required. I ensure that any new process reduces workloads and provides an audit trail.

Over many years, I've worked in MSWord and Apple Pages, PowerPoint and KeyNote, Confluence Draw.io and Visio, PhotoShop and Gimp, FrontPage and Dreamweaver, XMetal and RoboHelp, Notepad and Textedit, VSCode, Ford's Odyssey, Oxygen, Arbortext, Markdown for docs-as-code (web GUI and GitHub Desktop).

They all have pros and cons, but almost none allow topic-based libraries.

Why is topic-based content important?
• Consistent and flexible outputs
• Efficient & rapid publication

From a sentence describing the product's functionality to the scope of an SLA, consistency is essential. Write once, publish everywhere.

Topic-based libraries maximise content reuse, which helps ensure system-wide accuracy and reliability.

I prefer to work in MadCap Flare, which allows simultaneous development of web, mobile and print content.

A Flare project library consists of topics, snippets, variables, conditional text, content maps, publishing target configs (a combined definition of sources, templates, stylesheets and outputs), page layouts, stylesheet libraries: every element required for every document in any context.

Elements like legal notices and safety warnings are defined under advice from subject experts. They are stored as snippets that can be deployed anywhere, from a single source.

It is easy to address the reader individually: with a topic-based content library, you can build individual instances of a complex document that are unique to a specific customer's branding, configuration, sector, market, region or jurisdiction.

See Sample 7 for the library I developed to publish a unique Integrator Manual for every SkelGrid customer configuration.

Every sector has standards, rule sets and conventions that must be followed for a successful outcome.

Bids for defense contracts are governed by the S1000D standard. Those for UK government require adherence to PCR2015 and a range of compliance standards meeting current policy specifications.

Technical and commercial documentation is increasingly adopting ASD-STE100 (Simplified Technical English), which helps to remove ambiguity and prepares for translation and localisation.

Where the client is a government agency or a large organisation, there are often challenges to ensuring documentation requirements are adequately defined for success.

The technical writer works to ensure not just consistency and completeness of messaging, but that compliance is met with all governing standards.

Facing a complex bidding framework and limited time to submit?
Get in touch