Setup AEM Guides (XML Documentation for AEM)
Adobe Experience Manager (AEM) is a suite of software products from Adobe Systems that allows users to manage, create, deliver, and optimize digital experiences. AEM Guides is a new capability within AEM that allows creators to author, manage, and publish documentation and guides for products and services. In this blog post, we will cover the reasons to adopt AEM Guides for your documentation needs, the ways of configuring AEM Guides with AEM, and some of the Add-on customization possible. Furthermore, we will briefly cover working with dita files and publishing the output.
XML Documentation for Adobe Experience Manager / Experience Manager Guides, now referred to as AEM Guides is an application deployed on top of AEM. It enables native Darwin Information Typing Architecture-based (DITA) support in Experience Manager, allowing AEM to handle DITA-based content creation and delivery.
REASONS TO ADOPT AEM GUIDES
- AEM Guides is a powerful, enterprise-grade CCMS and therefore manages content at a granular level, unlike the document level. To maximize content reuse, it stores words, phrases, chapters, and sometimes even entire procedures in a central repository.
- Maximizing content reuse means less original content needs to be translated. This strategy could save money on translations.
- Imagine you have dozens of similar products that share the same content. Updating all related content for each product separately will be a huge task and may result in hundreds of errors. With DITA XML you can write the content in modules, that can then be plugged into wherever needed. Reusing content like this across publications in the organization can save a fortune and enhance consistency and high quality.
- Each of the components is stored only once, which makes a trusted and consistent single source from which content material could be released across multiple platforms, for example: for print, mobile, or desktop.
- It empowers authors to create content using any offline DITA authoring tools or an easy-to-use built-in web editor. (bonus tip below this 😉)
- Single-click Publishing capability generates DITA-based output in the most popular formats — Experience Manager Sites, PDF, HTML5, EPUB, and custom output through DITA-OT.
- Localization Time and Costs also reduce significantly
- ensures uniformity and consistency in pre-and post-sales content while providing seamless and personalized experiences to end users.
- Structured Content Management capabilities like advanced content reuse, version management, reference management, search and metadata tags management, translation workflows and content health reports to assume complete control of your content.
- Adds intrinsic intelligence to content using artificial intelligence and machine learning, powered by Adobe Sensei, for super-fast delivery and simpler content discovery by customers.
- Saves time and effort through a web-based review workflow. Allows multiple authors and reviewers to collaborate simultaneously in real time even when operating remotely. Roles can be assigned using projects, and admin dashboards can be used to monitor progress.
- Omnichannel content experiences — Accelerate content velocity across touchpoints by easily delivering content to Adobe Experience Manager Sites, mobile apps, knowledge bases, CRM platforms, IoT Apps, chatbots, PDF, HTML5, EPUB, KINDLE, and more.
- Can create granular, presentation-independent, variant-free content quickly and easily with the WYSIWYG web editor. The out-of-the-box ingestion framework helps to convert content from Word, XHTML, IDML, and other formats to DITA.
Bonus Tip: Offline DITA Authoring Tools that will ease content creation, click on them to know more.
Heretto (formerly Easy DITA)
WAYS OF CONFIGURING AEM GUIDES WITH AEM
AEM Guides is a plug-in that installs on top of Adobe Experience Manager.
AEM Guides packages are available in two modes — UUID build and non-UUID build.
Customers will need to decide between UUID and non-UUID mode at the time of first setup. When upgrading from one version of AEM Guides to a newer version, customers will need to ensure they pick the same mode to match their existing mode. A non-UUID build should not be directly upgraded to a UUID build. Moving from a non-UUID build to UUID build would need content migration.
You can set up your AEM Guides with AEMaaCS as well as AMS or On-Prem.
NOTE
Reach out to your Customer Success Manager for access to AEM Guides builds for AEM as a Cloud Service.
Having said that, let’s see how to configure AEM Guides onto AMS or On-Prem
Prerequisites
Adobe Experience Manager
• Version 6.5 Service Pack 12, 11, 10 or 9
IMPORTANT: For AEM Site output generation, your AEM’s publish instance must have Service Pack 12, 11, 10, or 9.
Java Development Kit
• Oracle SE 11 JRE 11.x
• Oracle SE 8 JRE 1.8.x
Web browser
• Google Chrome (preferred)
Step 1 — Install AEM 6.5 On premise version
Step 2 — Run your instance server
Step 3 — Now go to Adobe Software Distribution and download the below packages AEM 6.5 On Premise.
- Latest Service Pack from AEM 6.5 Service Pack
- Latest UUID / Non-UUID Release for XML Documentation for AEM 6.5 from UUID & Non-UUID Release
Step 4 — Now get to the CRX package manager and install the above downloaded packages as per the below order.
- First install the Service Pack.
- Then install UUID / Non-UUID Release for XML Documentation for AEM 6.5.
Setup 5 — Now go to your AEM dashboard home page and from there you will be able to access XML Editor.
Once you have installed AEM Guides, you need to verify whether the installation was successful or not.
Perform the following steps to verify the installation process:
1) Log into your AEM instance and navigate to the AEM Web Console Bundles page. To visit the bundles page, enter the following URL:
http://<server name>:<port>/system/console/bundles
A list of bundles is shown.
2) Filter the list of bundles by entering fmdita in the filtering textbox and pressing Enter. The list of bundles is filtered to show the bundles installed by AEM Guides.
If the installation was successful, then all installed bundles will have a Status of Active. If any of the bundles do not have an Active status, then check the AEM logs to troubleshoot the installation issue.
Configuring AEM Guides onto AEM as a Cloud Service
Firstly, have your AEMaaCS instance server up and running
The AEM Guides are made available through the GitHub repository. You can download the AEM Guides from the GitHub repository and install it.
Deploy AEM Guides module
You can start by deploying AEM Guides via the Cloud Manager. To deploy the module you can follow the instructions mentioned in AEM Guides as a Cloud Service deployment.
Verify AEM Guides installation
Once you have installed AEM Guides, you need to verify whether the installation was successful or not.
Perform the following steps to verify the installation:
1) Access the Developer Console of your Cloud Service.
For details on accessing the Developer Console, see Developer Console access in AEM documentation.
2) Access the list of OSGi Bundles in AEM.
For details on accessing Bundles, see Bundles in AEM documentation.
3) Search for fmdita in the list of bundles and check its status.
The status should show Active for successfully deployed bundles. If any of the bundle does not have an Active status, then check the AEM logs to troubleshoot the installation issue.
For more — If you are new to XML Documentation, then you should go through the hands-on training for better understanding. Check out the link below for a video tutorial.
Customization features available in AEM Guides
Use custom DITA-OT
The DITA Open Toolkit (DITA-OT) is a set of Java-based, open-source tools that provide processing for DITA maps and topic content. AEM Guides allow you to easily import and use custom DITA-OT plug-ins. Once imported, AEM Guides can be configured to use the custom DITA-OT plug-in to generate output in any format. At the time of generating the output, simply
select the DITA-OT option and the AEM Guides uses the custom DITA-OT plug-in to generate the required output.
DITA specialization
DITA specialization is the process of developing new DITA structures through the addition of fresh elements or the deletion of old ones. It is possible to create a new DITA element by taking an existing DITA element and modifying it according to your authoring needs. In essence, DITA specialization allows you to create customized information models that meet your business requirements while retaining the benefits of the existing DITA architecture.
Customize Web Editor
AEM Guides comes bundled with a powerful Web Editor that allows your authors to create and edit DITA documents. You can customize the Web Editor’s toolbar to add or remove any feature that you can access from the toolbar. Also, you can configure auto-savings of files, generating IDs for elements as they are inserted in your documents, and much more.
The following sections cover the features that you can customize in the Web Editor:
• Customize toolbar
• Configure file auto-save in the Web Editor
• Customize AEM’s default dictionary
• Auto-generate element IDs
• Configure allowed special characters
• Configure filters for file browse dialog
• Configure display of UUID-based links
Customize AEM Site output
The AEM Guides support creating outputs in the following formats:
• AEM Site • PDF • HTML5 • EPUB • Custom output through DITA-OT
For the AEM Site output, you can assign different design templates with different output tasks. These design templates can render the DITA content in different layouts.
For example, you could specify different design templates for internal and external audiences. You can also use customized DITA Open Toolkit (DITA-OT) plug-ins with the AEM Guides. You can upload these custom DITA-OT plug-ins to generate PDF output in a specific way.
And many more feature customizations are possible.
WORKING WITH DITA FILES
Before we start working with DITA XML, let's know what it actually means
DITA stands for “Darwin Information Typing Architecture.”
In retrospect, the “Darwin” word in the name makes perfect sense since it is based on inheritance. Child elements “evolve” from the parent elements and are based on them.
XML stands for “Extensible Markup Language,” which is a system that uses tags to tell the computer what to do with the text. It has opening tags and closing tags surrounding the text
For example, the HTML tag <h1> tells the browser that the text should be a large heading, and the tag <p> tells it that the text should be a paragraph. There are similar tags in DITA that tell computers what the content is.
Building Blocks of DITA: DITA Topics
Since DITA is a topic-based authoring standard, the building block of any DITA file/project is ‘Topic’. We represent it with the tag <topic> in a DITA project.
In the words of ‘OASIS’ — What is a Topic?
“In DITA, a topic is the basic unit of authoring and reuse. All DITA topics have the same basic structure: a title and, optionally, a body of content. Topics can be generic or more specialized; specialized topics represent more specific information types or semantic roles, for example, <concept>, <task>, <reference>, or <learningContent>.”
We then combine different topics together to form a “map,” which we transform into different DITA output formats (e.g. HTML, PDF, etc) as per requirements.
What is a DITA Map?
A DITA map is a kind of XML file composed of references to individual topics. By using references to topics, the DITA map file pulls together the topics into a collection to form an entire document.
Various topic types can be used depending on the type of information being documented.
As part of the DITA architecture, there are four standard topic types:
- Concept — contains background information that answers the question “Why?”
- Task — contains procedural information that addresses the question “How?”
- Reference — contains facts, frequently in a table, about a topic that answers the question “What?”
- Glossary entry — defines a single term and gives the meaning of it, answering the question “What does it mean?”
Okay, that’s pretty much about DITA XML Topics & MAP. Now, let’s jump into the XML Editor from the AEM Navigation page.
From the sidebar, you can choose from multiple views for the XML Editor to best suit your organizational needs. The default view displays your Favorites. You can further customize it with shortcuts as needed. Conversely, the Repository View displays a more traditional folder structure.
Viewing content in the Assets UI
You can perform additional actions with your content. One of these options is to view your file in the Assets UI.
Hover over a folder or topic in the Repository and select the ellipsis icon that displays.
Creating a folder
- Select the Repository icon to view your folders and files.
2. Select the + icon and Folder.
- Give the folder a title.
- Select Create.
You have created a new folder, which now displays in the Repository. This folder will be your home for all course content.
Creating a subfolder
We can now create a folder inside your new folder to contain images or other content
- Hover over your new folder in the Repository and select the ellipsis icon that displays.
The Options menu displays.
2. Select Create > Folder.
3. Give the subfolder a title (for example, “images”) and select Create.
Creating and populating a new concept
- Hover over your parent folder in the Repository and select the ellipsis icon.
2. Select Create > Topic.
The Create New Topic dialog displays.
3. From the Template dropdown menu in the dialog, select Concept.
4. Give your concept a title and select Create.
The new concept is displayed in the editor, populated with its title.
5. Populate the concept by clicking on either the short description or paragraph and typing your content.
Creating and structuring the content
Once you determine the topic type that your DITA structure has to follow. You can create the topic DITA File and start typing the content into your dita file, as easily as you can type any word document in Author mode.
It supports the usage of Plain text, lists, Tabular Columns, Images, Multimedia, Cross-references, links, inserting reusable content, Special characters, inserting keywords, snippets, Enabling/ Disabling Track changes, Merge option, Version History, Version Labeling, Creating review tasks.
The above is an example of a Concept dita with some text, a hyperlink to an external document and an unordered list in Author mode.
The dita format for it could be seen by switching to the Source mode, content can also be edited in the source mode too, by adding the appropriate tags.
Preview mode gives us a preview of the document.
In Author mode, on the right trail, we can see the Content properties, File properties, Review feedback and comments, Tracked changes, and Schematron Validation.
Save and Save as New Version
You can save your work at any time with Save or Save as New Version. Use Save to keep your changes, and use Save as New Version to create a new version of your topic with current changes.
Saving your work without versioning
- Select the Save icon.
Saving as a new version
Select the Save as New Version icon on the right of the Save icon.
The Save as New Version dialog box displays.
In the Comments for new Version field, enter a brief but clear summary of changes.
In the Version Labels field, enter any relevant labels.
Labels allow you to specify the version you want to include when publishing.
NOTE
If your program is configured with predefined labels, you can select from these to ensure consistent labelling.
Select Save.
You have created a new version of your topic, and the version number is updated.
Versioning Content
Now, we can save this document as a new version with a version label. Eg: 1.0. Once you save your DITA File with a version label, it can be seen at the top-right corner of the editor.
And continue, editing to make further changes and save this as a new version, Eg: 2.0.
Now, if you click on version history on the toolbar. You will see a window that shows the two versions of your document along with the version label, version comments, document preview and an option to revert the document to a selected version.
The merge option in the toolbar, helps you to track changes from a selected version and revert to a selected version or merge two versions of a document.
Uploading DITA Files into AEM
DITA Content created using other offline DITA Authoring tools can also be imported into AEM as Assets.
Click on the ellipsis of the folder, where you want to import the Externally authored DITA files, and click on the Upload Assets Option. Choose the DITA Files you want to upload here and click on Upload.
Creating a Map
A map is an organizational tool that lets you add and organize information in a hierarchical structure.
To create a map, select the ellipsis icon on your desired folder. Select Create > Map. The Create New Map dialog displays.
- In the Template field, select Bookmap from the drop-down menu and give your map a title.
- Select Create.
Your map is created, and the left rail automatically changes from the Repository view to the Map view.
Insert map components
- Select the pencil icon on the left rail.
This is the Edit icon and allows you to open the map in the editor.
2. Switch back to the Repository view by selecting the Repository icon.
3. Add a topic to the map by dragging and dropping it from the Repository into the map in the editor.
The line indicator shows you where your topic is placed.
4. Continue to add topics as needed.
The author and source mode works the same as the DITA Topic in DITA Map too. Clicking on the preview mode, enables you to see the full content that has been added to the Bookmap in the chapterwise order.
The toolbar of the DITA Map, has a few additional options to explore such as Insert before and after — to order the topic in the Map, Insert Elements, Insert Topic Reference, Insert Topic Group, Insert Chapter, Insert Key Definition, Insert Relationship Table, Insert Reusable Content, Refresh Navigation Title Attribute, Lock, Toggle Tag Views and other options same as DITA Topic.
Publishing the Output
Once you have a completed map, you can publish your content in multiple output formats.
In the repository, select the ellipsis icon on your map to open the Options menu, and then Open in Map Dashboard. The Map Dashboard opens in another tab.
In the Output Presets tab, select the output preset that you want. Eg: AEM Site and PDF.
Select Generate. Navigate to the Outputs page to view the status of your generated outputs.
A green circle indicates that the generation is complete.
A yellow circle indicates output generated with errors.
Clicking on the PDF, enables you to download the Generated PDF.
Clicking on the AEM Site, redirects you to the output site.
To view the error logs, you can click on the Corresponding Time and Date shown in the Generated At Column.
The AEM Site Output
In the AEM site output, topics, lists, images, titles, tables, and other content created with the XML Editor are all automatically published to web-friendly content by AEM.
You can see subordinate topics in the table of contents as well as in the Related information section. These links can all be used to navigate.
Upon clicking any of these links, you can view it in the below format.
The PDF Output
The finished PDF document contains the default title of the map as the main title on the cover page. Chapter cover pages are styled with the chapter number, and contain links to the topics within.
To know more about Output Generation with AEM Guides, take a look at the below link Output Generation with AEM Guides.
AEM Guides are a great way to manage your AEM content. With a few simple configuration changes, you can easily customize AEM Guides to fit your needs. This will allow you to take advantage of the many features that AEM Guides has to offer, such as versioning, content reuse, web-based review workflow, omnichannel content experiences and much more.
Phew! That was a long blog indeed. And with that, we’ve reached the end of our AEM guides expedition!
Happy guiding, my fellow techies!
