Everybody is or will be impacted by the accelerating pace of product launches and updates.
Software vendors are moving to agile with ever-shorter release cycles, and new versions arrive every month, every week, or even every day. This trend is reinforced when providing software as a service. With microservice architecture and DevOps practices, new features and bug fixes get rolled out immediately. Security enhancements must be deployed on the spot. Putting software into production happens all the time, at any time.
In one way or another, vendors of hardware products experience the same transformation. Periods between product versions are shorter. Smaller production batches set the stage for improvements and variants. Furthermore, embedded software modifies product behavior and capabilities. Hardware becomes malleable thanks to massive innovations such as the platformization of production, 3D printing, and Industry 4.0.
How can tech doc keep up with this transformation and keep pace with products as they change? How is it possible to deliver documentation in real-time, in sync with each new version that is rolled out to production?
This is a tremendous challenge that tech doc departments face, and they must meet it or else risk slowing down or jeopardizing business. It is also a great opportunity to play a major role in an organization’s digital transformation by reinventing how tech content is produced and delivered, thereby enhancing customer support and field service operations.
Finding the solution means reconsidering the entire paradigm of how information is produced, published and delivered, including people, tools, processes and workflows. Let’s divide it into two main phases: information production and information publishing.
Information production
The challenge is pretty simple: increase writing throughput so that content generation is in sync with product evolution and is ready at the same time as the new version.
You have two options:
- Scale-up (more of the same): add more tech writers, or
- Scale-out (change it up): involve other people in producing content for the company.
The scale-out approach requires more work as it means changing how things are done. However, it is certainly the way to go as it makes content production light-years faster and also creates more diverse content. It extends the idea of leveraging subject matter experts -SMEs- by including more stakeholders in the process: product owners, developers, engineers, QA, … Clearly, not everybody has writing skills, but by setting up a proper framework with shared guidelines, rules and tools, anyone can become a valuable and engaged contributor.
See this as the reversal of the common process:
- Traditionally, tech writers interview people, try to understand every bit of the product, and then draft manuals and have them reviewed by SMEs for accuracy.
- With the new paradigm, tech writers would design the storytelling -what needs to be written- and then have experts fill the blanks -write their part of the story. Tech writers would also review, proofread and align content to ensure its consistency.
A typical example would be to let developers write the documentation for software APIs. Since they speak the language of developers, they are the most apt to explain how to use these APIs, but they probably need the expertise of tech writers to do it the right way. And developers will certainly use their own authoring language, such as Markdown or OpenAPI. Indeed, the change of paradigm entails that you must let each group of stakeholders work with the tools they are most comfortable with. You cannot impose structured authoring -such as DITA- to the entire company, and the idea that single sourcing requires single authoring is a mistake. Let them write with Word, Markdown, AsciiDoc, in a Wiki, or anything else. Let them be productive.
Aggregating and aligning content to create a unified repository of knowledge has to be handled downstream by the delivery layer. With this new strategy, beyond defining what needs to be produced and by whom, the role of Tech Writers consists in anticipating how to achieve consistency across multiple content providers and sources, such as by providing taxonomies and instructions on how to tag with metadata to the different stakeholders.
Real time, in-sync publishing
The second phase involves making content available to users, partners and distribution channels at the right time, which means “as soon as the product is available.”
In the paradigm where products are released every few months or years, the process is well-known and relatively easy to orchestrate. Tech doc is always under pressure because the product must be finalized in order for tech writers to get the most recent and accurate information for the documentation (a feature description and screenshots, for example). But in this mode, the time required for content creation is allotted within the product release schedule, including for generating content in its delivery format (PDF, static HTML) and asking IT to deploy it to a website.
When product delivery is continuous, there is no time for batch content generation, extensive content review, or asking IT to move content from internal staging servers to the website. Publishing -pushing the button to ‘export’ content- and delivery -the content is accessible- must be one step. The journey from the backend (content production) to the front end (content exposure) must be streamlined.
This approach implies that content is pushed by the producers directly to the delivery platform. The platform then bears the responsibility of transforming the content received in its native format. The CDP -content delivery platform- must embed and provide all the technology and tools necessary to receive content as it is, transform it, and align metadata. What’s more, the CDP must support the content staging and reviewing process. It must provide functions that limit access to new content to specific stakeholders until validation, and it must provide tools so that reviewers can send feedback to the authors.
Another benefit of this approach is that new or updated content is immediately accessible. Why wait weeks or months before releasing a user manual that is up to date or a troubleshooting guide that has been improved?
It must also be possible to publish content for an upcoming product or version without delay, reserve early access to selected individuals, and keep this content under wraps until the grand opening. Content visibility can even evolve dynamically by simply changing some rules. This way, your distributors can see some information in advance, get up to speed, and be ready to support customers on D-Day.
Last but not least, content publishing could and should be automated and incorporated into your delivery process. For example, software vendors can integrate the generation of a Release Note with the development team’s Continuous Integration-Continuous Delivery tools and trigger its visibility as soon as the software is successfully rolled out. This way, tech doc is always in sync, with minimal work. In an upcoming blog post, we will explain how Fluid Topics Release Notes are automatically created and published by a bot that synchronizes with our CI/CD system.
As we have discussed, the radical transformation that is underway for many industries obliges us to reconsider how tech doc is produced. But it is also a great opportunity to redesign the process to make it more efficient, inclusive and embedded within a company’s core activities. It’s a unique moment for tech doc departments everywhere to contribute to digital transformation.
About The Author
