Have you ever helped people execute a complex task by explaining it to them in writing, by drawing, or by giving them a demo? Did you then think about saving that explanation somewhere it could easily be found? And, after a couple of days, did a new question pop up? And another? Did you then consider making all answers available to your customers, your colleagues, their bosses, the world? Welcome, you are one of us, practicing the noble art of technical communication. It can be hard work (and an acquired taste to some). To help you, and because technical communication is an underexposed domain as it is, this whitepaper lists some interesting opportunities for automation that will help you to develop better documentation in less time. Some of them even without AI!
Opportunity 1: Writing faster with assistants
Brain-computer interfaces that automatically transfer your thoughts onto the screen may not be a reality yet, but there has been an impressive evolution in writing assistants and editors. While writing this (in Word), I have Copilot, Microsoft’s AI assistant, open. It suggests improvements. It helps me find stuff. It summarizes what I feed it. When asked, Copilot even writes me a short definition of ‘writing assistant’, like this:
A writing assistant is a software tool that helps technical writers create, edit, and improve their content. A writing assistant can provide suggestions, feedback, corrections, and enhancements based on natural language processing and artificial intelligence. Some examples of writing assistants are Copilot in Word and the Oxygen AI Positron Assistant.It actually is even more useful when you are writing technical content. That type of writing usually follows stricter formats and implies simpler, easy-to-read structures. At my request, Copilot transformed the above definition of ‘writing assistant’ into a list:
A writing assistant is a software tool that helps technical writers create, edit, and improve their content. A writing assistant can:
- Provide suggestions, feedback, corrections, and enhancements based on natural language processing and artificial intelligence
- Support various formats, languages, and standards of technical documentation
- Integrate with popular writing platforms and tools
Some examples of writing assistants are Copilot in Word and the Oxygen AI Positron Assistant.
By the way, the AI Positron Assistant in Oxygen XML, a cool tool that technical writers use, has a similar instruction for making lists, called ‘itemize’. It is one of the pre-made prompts that are neatly grouped into a set of buttons. You can create your own and even record a sequence of prompts if you want to use it more often.
Opportunity 2: Writing better with editors
Many organizations have formal review and approval processes. These processes tend to be quite laborious, but are usually automated already by your document or content management system, if you have one. If you don’t, Power Automate or Python can help to automate steps: sending documents to reviewers, collecting feedback from users, updating statuses…
But that is the easy part. It is notoriously difficult to review what you have written yourself. Automated editors have evolved from having it wrong most of the time (even spell suggestions, remember?) to having it right most of the time. Use them!
These days, pretty much every tool has built-in editors that can provide all or many of the following:
Predictive text
Spelling, grammar and punctuation checks
Writing style checks
Clarity, conciseness, inclusiveness checks
Terminology suggestions and clarifications
Acronyms clarifications
Readability scores
In Word there is Editor, which does all of the above. It takes no more than minutes for a text like this one and is extremely reliable (though never 100%, which is reassuring, in a way).
Imagine what an Editor/Copilot integration could do.
In the meantime, templates, a custom ribbon and buttons in Word can also help. Here’s an example of a Word ribbon using a specific, semantical structure. Note how the custom buttons are grouped and labeled to guide the writer:
So does this mean that writing better content has become easier? Yes, it definitely has, as we have discussed above. It’s a small effort because of increased automation and it will save reviewers time. But also, no, it definitely hasn’t. Content increasingly is a moving target because of the complexity of organizations and their products and services.
Opportunity 3: Reusing content
One way of writing faster and better is by reusing what you already have. There are two use cases here: linked reuse and generated reuse, as these two examples show:
Say you are responsible for train maintenance at a railway operator. Documenting work instructions for a specific type of railway carriage is no easy feat. What if you have railway carriages of a similar type, but not entirely the same? What if you have instructions that are the same for all types, but not the accompanying pictures?
In that case you need to create content that is composed of intelligent building blocks that enable automated, linked reuse, for example using XML-based standards such as Darwin Information Typing Architecture (DITA) or S1000D. Written once, published everywhere. Updated once, updated everywhere. Efficient, linked reuse.
A very different, but equally rich way of reusing existing content is provided by generative AI applied in a custom environment. Copilot enables you to use documents and information that you or your colleagues have created before in a new document. That type of reuse isn’t linked but a ‘generated’ copy. It would be nice if this type of reuse could be set as strict (exact info) or less strict (inspired on).
Opportunity 4: Connecting content with data
Up until very recently, documentation has been living on an island. Technical content wasn’t connected to the product (hardware or software). It also wasn’t connected to information that is stored on other islands, about spare parts, consumables, customer data, publications, forms. Documentation wasn’t (and often still isn’t) connected to information that is the result of actions performed by the user, such as test results, measurements, detections, checks, nor was it connected to customer knowledge, support departments or knowledge bases. This is changing rapidly.
Like most business domains, documentation is currently discovering that there are other islands surrounding it.
At Flow, we now connect instructions to entreprise systems (such as ERP), guaranteeing up to date info (if the ERP is up to date). The spare parts and consumables can be searched from a list and are referenced: no more confusion or discrepancies. Translate this to a software environment and you are using software strings that match ever-changing button labels and other GUI elements, for example.
There are several tools on the market today that are building bridges between different worlds, er… islands, today. In operator environments, and installation or configuration, there’s Proceedix (recently acquired by SymphonyAI), for example, and augmented reality-based systems. Another content island is learning content, which presents obvious but often overlooked opportunities for reuse. And some tools are underway to tackle this, such as Whale. In customer support, we are seeing efforts to better integrate with documentation. A support agent consults solutions to problems that are stored in a knowledge base in CRM environments such as Dynamics or JIRA. The challenge is to make sure that those documented solutions fit all the environments in which they are used: manuals, support portals, human-machine interfaces (HMI), public websites etc. Finding cases and integrating tools is one thing, creating the right information architecture and governance, and finding skilled information managers is another.
The bottom line: connecting data, information, and domains is happening everywhere, also in technical content. It is a huge win in efficiency and customer comfort.
Opportunity 5: Automating publishing
For years now, publishing has been a major candidate for automation in many organizations. And while it takes a strategy and a plan (and possibly some restructuring and conversion work), it is a major win that many aren’t, but should be, considering. In many cases, this is the proverbial low-hanging fruit!
Here are some of the automated publishing opportunities:
Automated publishing flows to channels such as web, app, online help, interface, PDF
Rebranding content on the fly
Filter content (think online shopping)
Conditional publishing, depending on rules such as audience and device
Automated publishing from repositories such as GitHub
Integration with translation services and memories
This isn’t new, yet it is often not implemented. The reasons are straightforward:
Technical communication as a domain is relatively unknown, and therefore its power and best practices often are not considered or only partially implemented.
Without the necessary expertise, change and conversion may come at a high cost. AI will help here, but even without, careful planning and taking it one step at a time will make the process worthwhile.
Automation opportunities for better documentation: What can you do today?
Poorly structured and unorganized information is the Achilles heel of any automation process. You need to lay the groundwork by structuring information first. There are different ways to do that.
Here is some advice:
Write less. Most people write too much. All that content becomes a maze to navigate and maintain.
Plan. Which type of documents do you really need? Decide on a clear purpose and criteria for each document or content type. Make sure that everyone who writes knows them.
Assess your documents. Use feedback from colleagues, customers, anyone who needs your documents to improve them and make them more useful.
Start using structured writing now. Waiting only creates more content to convert. Moreover, the quality of your output will increase.
Think about the above opportunities. If you have questions, don’t hesitate to ask.