A Bit of Background

Maintaining a user manual for an ever-evolving software program can result in documentation content becoming redundant, irrelevant, or incorrect as features are removed, updated, and added. Without a dedicated technical author who can regularly review and dynamically restructure content, user manuals can become chaotic and key information can end up buried from those who seek it.

The problem with one user manual was that the foundations of the content were based on developer documentation from ten years prior. Some original content was still very relevant, and other content was not. Over the years, multiple different authors carried out quick fixes, added big new features, made small amendments, and moved a few things around. When the time came to migrate this large and morphing user manual to a modularised system of DITA XML documentation, it was clear that some major work was required.

Taking ownership of this user manual required me to balance requests for adding new content with a complete restructure of existing content during an ongoing software development cycle.

I consulted with the team of software developers, subject matter experts, and the product manager. First, I discussed the business requirements, analysed the existing content, removed unnecessary content, and identified the gaps between the existing content and the requirements. Then, I grouped information coherently with consideration of the user experience, while working alongside the stakeholders to fill in the gaps with quality content. To reinforce user understanding, I created suitable diagrams and included screenshots within well-structured text.

The resulting architecture of information provided a clear and accessible structure of nested topics, including conceptual, reference, and task material. The consistent and logical format provided a structure considerate of facilitating future growth.

Faced with the expense of sending an enormous volume of technical user guide documentation for translation, the team I was part of set out to review and consolidate our information first.

We identified that writing documentation using DITA would allow us to re-use content efficiently and allow us to only send small sections of documentation for translation—instead of huge files.

Not only would this writing format be more cost-efficient, but the modular component style also lent itself to improving our content architecture.

Before commencing the huge project to re-write all documentation in DITA format, we agreed upon a detailed style guide and consistent formatting rules. Each of us considering the content within our area of expertise.

I began by analysing the content in my areas of responsibility and started planning the new structure. Using XMetal authoring tool, I created a series of DITA XML topics and used RWS Tridion docs to organise these into the intended structure within DITA maps. This included writing concept, task, and reference topics, creating internal and external links, adding metadata, images, index terms, and library topics for re-useable content.

Working according to tri-annual release cycles in alliance with software developers, product managers, and other stakeholders, I created, edited, and maintained material for user guides, theory guides, tutorials, and some training materials. Extensively using JIRA and Confluence for task management and collaboration.

I coordinated localising material for each release. This included preparing and sending material to translators in advance of each release and resolving queries by liaising with external translators and internal subject matter experts—particularly to ensure accurate terminology of highly specific technical GUI strings.

By keeping track of new features throughout their software development cycles, I learned about the intricacies of the features, and formed a deep understanding of the nature of the problems that they solved for customers. In advance of major new feature releases, I worked with the product managers, SMEs and developers to build simple yet effective tutorial cases that would showcase the highlights of the new software features.

Working with new features within a CFD software program, I imported 3D-CAD models of relevant geometries then gradually set them up within the software and ran simulations of scenarios to completion. With notes and repeated run-throughs, I created step-by-step tutorials. This process required patience, perseverance, and the ability to adapt dynamically.

As an advocate of great user experience, I always strived for continuous improvement of the documentation. I spent some time using Google Analytics to monitor customer usage of the user guide and tutorials then created reports to assist senior managers with decision making. Having enjoyed the analytical nature of this task, I then proceeded to work in cooperation with the knowledge manager to analyse customer feedback from surveys—targeting those which related to documentation. For cases with a negative review, I investigated the issues and created tasks for the team to resolve these where possible—driving up our team's overall quality rating.