Technical documentation with Adobe Experience Manager
In late 2022, Adobe invited selected partners, interested parties, and customers to the first AEM Guides Meet-Up in Germany. Michael Deiß and I did not miss the chance to get to know the roadmap of the solution and the management, marketing, and engineering team of the AEM Guides Business Unit.
AEM Guides is a so-called CCMS (Component Content Management System). It enables companies to easily create and reuse technical content as centrally managed content – for example, for further instructions or other language versions. In companies, AEM Guides is the digital platform for the “HOW,” i.e., how do I install ABC, how do I repair XY, or how is “this and that” put together? Other digital platforms, such as a classic CMS, are responsible for the “WHAT” and “WHEN.” Ensuring the content’s accuracy and consistency is of central importance with these systems.
AEM Guides version 4.1.2 has been available on-premise for a few weeks now. AEM Guides As-a-Cloud-Service receives monthly updates. AEM Guides is not new, but the name is: until recently, the solution had the cumbersome name “XML Documentation add-on for Adobe Experience Manager.”
AEM Guides - where are you?
AEM Guides integrates with Adobe Experience Manager Assets. Therefore, you can manage technical illustrations and marketing assets in AEM Assets. XML and DITA have become the international standards for technical documentation. AEM Guides, therefore, comes with a range of visual XML editing tools. Content creators can use these tools to create so-called DITA topics and DITA maps. DITA stands for “Darwin Information Typing Architecture.”
- Darwin – DITA uses specialization and inheritance, analogous to Charles Darwin’s ideas on the origin of species.
- Information Typing – Information units are typed (classified) in DITA according to their content.
- Architecture – DITA is an Information Architecture. It is not simply a DTD but includes rules for deriving new information units.
DITA, in turn, is an OASIS standard (Organization for the Advancement of Structured Information Standards) that provides an XML-based information architecture created specifically for maintaining complex documents and information. With DITA, you can manage large documents and entire groups of documents using uniform concepts for content reuse.
Many companies now see the need to rethink technical documentation.
When we talk about technical documentation, we also mean operating instructions, training documents, product catalogs, data sheets, assembly instructions, etc. In the past, there were mainly these two “clusters” when it came to creating these documents:
- Companies and technical writers who “think in manuals”: However, this approach leaves out the possibilities of other output formats, such as website and app: Visual design, customer experience through lack of personalization, multi-device delivery (PDF vs. mobile), and marketing potential through cross-sell / up-sell / lead generation via digital channels suffer.
- Companies and technical writers who “think in marketing and sales processes,” neglecting norms and standards.
The charm of AEM Guides is that the solution serves both “clusters.” However, before we get into the technology, I would like to start by writing a few sentences about the two basic technological approaches:
Most manufacturing companies currently (still) rely on desktop tools, which – often customized and extended – can become monolithic systems. Unsurprisingly, the most widely used desktop tool for technical documentation is Microsoft Word. Enterprises often customize Word to many requirements through macros, text modules, and formatting but quickly reach its limits due to the nature of the unstructured data. On the other hand, specialized tools such as Adobe FrameMaker offer the possibility of working in a structured, i.e., rule-based and modular way with the help of templates. Technical editors define how headings, continuous text, lists, images, etc. are to be displayed. FrameMaker has a kind of book structure, i.e., there is a main document with many sub-documents (chapters etc.), and FrameMaker can use different sources.
Content can be entered directly into FrameMaker or imported via appropriate interfaces. The result is a structured text: The system can consider the text lengths of different language versions in the output, which can be of different lengths, depending on the language version. In the case of unstructured texts, the result of the translated language version would look different because, for example, breaks would no longer fit or tables would not be displayed cleanly, etc. The result is a structured text.
Such a rules, dependencies, and connections structure can eventually become a complex monolithic system. Many companies are, therefore, in the process of breaking down these complex systems. Tools like FrameMaker are only used as authoring tools, while modules, variants, and conditions are managed in a dedicated content management system. The XML-based DITA standard has become the accepted international format for technical documentation.
Component Content Management System
Various providers have jumped on the bandwagon of CMS-based documentation tools. Many companies already use a CCMS for technical documentation. However, AEM Guides has the decisive advantage that the solution builds on the world’s leading CMS (AEM), and customers benefit from many out-of-the-box AEM features that go far beyond the standard. These include workflows, automatic translations, asset management, artificial intelligence automation, omnichannel output, and integration with other Adobe Experience Cloud tools such as Analytics and Target.
EM Guides also comes with its own web-based XML editor. Technical editors, therefore, do not have to take the “diversions” via an external XML editor. At this point, one might ask what the raison d'être of a desktop editor is in perspective: it is probably primarily offline work on documents.
Adobe Experience Manager Guides - structured content for experience-driven documentation
With AEM Guides, the complete lifecycle of technical documents can be implemented, from creating or importing content through administration and review processes to personalized omnichannel delivery.
The user-friendly web editor allows the creation of content independent of presentation. In addition, you can ingest content from Word, HTML, Markdown, InDesign, and many other formats and transform them to the DITA format via a separate framework.
AEM Guides offers the best content management features currently available, such as advanced content reuse, version and reference management, tag management for search and metadata, or translation workflows.
Artificial intelligence and machine learning based on Adobe Sensei enable fast delivery and more accessible content discovery.
Web-based coordination saves time and allows multiple authors and reviewers to collaborate in real-time. Administrators can assign different roles to users and track progress via admin dashboards.
Organizations can then provide technical content in various channels like web, app, portal, print, or PDF.
Machinery Directive as a killjoy for digitalization
Technical documentation can be published natively to Adobe Experience Manager sites via AEM Guides. However, through publishing engines and REST APIs, content can also be delivered to many other touchpoints, such as HTML websites, CRM platforms, IoT apps, chatbots, Amazon Kindle, etc. The benefits of digital delivery are apparent:
- You can analyze the consumption of digital documentation (how often which docs are retrieved, how are they used)
- Organizations can leverage the technical content in a broader marketing context (personalized content and offers)
- Documentations are responsive and are displayed optimized on all end devices.
However, the Machinery Directive 2006/42/EC still requires that printed instructions for use accompany a delivered machine and that, within the European Union, these instructions have to be translated into the official language of the exporting country.
But even this is not a problem because the provision can also be made by native publications in Adobe PDF and as a printed product.
The more complex the device – the more difficult the documentation
We all know the saying, “a picture is worth a thousand words.” In the field of technical documentation, we can extend it as follows:
“A picture is worth a thousand words; a 3D model is worth a thousand pictures.”
The legislation still requires printed instructions, but the trend is toward interactive content presentation. 3D equipment models have been viewable as Adobe PDFs in Adobe Reader for many years. (CAD design drawings created with Auto-CAD, for example, can be embedded in a PDF via an Acrobat plug-in. This, in turn, can be opened by end users in the free Adobe Reader).
But Adobe also offers the possibility of displaying 3D assets for the web world through AEM Assets Dynamic Media.
Why did customers choose AEM Guides? What are the significant drivers?
Every company that makes something needs a technical documentation solution.
Images, videos, animations, and 3D models are international. They don’t need to be translated and describe more than words. These assets will increasingly become the focus of interactive documents.
Customers want a smooth transition from marketing to technical documentation. There is still a large discrepancy between the two in terms of presentation, quality, and modernity. There should no longer be a noticeable difference in the future, as both are equally part of the customer experience.
Companies are literally thirsting for a solution. In many companies, Tech Doc departments have to “beg” for support in the design department. In the daily (cross-departmental) work, there is great potential for efficiency gains and cost savings, for example, through automated translations, content reuse, or coordination workflows.
We have now talked extensively about the “HOW” platform of companies. Once everything is perfectly documented and visualized, the only question is how to train employees to implement the corresponding measures. Adobe has a corresponding AEM extension for this as well, namely AEM Learning Management (formerly Captivate Prime). But we will go into this topic in more detail another time.