XML Documentation Add-On for Adobe Experience Manager – First Impressions

I’m going to start using the XML documentation add-on for Adobe Experience Manager and say goodbye to MadCap Flare soon.

The XML documentation add-on for Adobe Experience Manager is an end-to-end component content management system for structured content, that is built upon Adobe Experience Manager, a CMS.

To prepare for this new tool, I’ve been reading articles and watching videos to dive into the topic. My first impressions so far have been very positive, I’ll use this article to collect my thoughts on it.

This is what I like about the tool:

All content can be stored centrally in the Assets component. Adobe has built a lot of capabilities targeted at technical writers:
o A DITA Web Editor
o Review & approval collaborative tool – dev, PM, support, etc. can provide feedback and help to improve the content.
o Reporting capabilities – helps you check the readiness of the content.
o Translations are processed automatically. You can say goodbye to manual tedious processes (to a certain extent, of course). The content is automatically pushed to a translation vendor when the topic is updated. Then, you can re-import the translated content, and eventually review and approve it.
o Publishing tool (online, PDF, more formats)
o If you have Adobe Analytics, you can get more information about usage.
The add-on can be integrated into DITA authoring tools, for example, FrameMaker.
The user interface is user-friendly and intuitive.
You can check out topics for editing, which prevents conflicts (no more merges in GIT!)
AEM has its own version control system. When you have finished editing a topic, you can simply “save the revision” to create a new version of the xml. You can also add a comment to help you track your changes. AEM allows you to compare two versions and revert the content to a previous one. You can see the current version of a topic at the upper-right corner.
When you edit a topic, you can see the context in which it is inserted.
AEM has a graphical interface (Author view). You are not presented with a lot of tags. You can also change the view to code editor, which is context-aware. That is, the editor gives you a list of supported elements that can be used in the context, based on the previous and following element. One more good thing about the editor is that it identifies and flags syntax code errors (real-time validation).
The breadcrumbs are also an advantage. In MadCap Flare, you need to hover over the topic title to see the path.
A nice feature compared to MadCap is that you can edit all the elements included in a topic without having to open them, selecting them is enough.
The buttons in the toolbar are the standard ones: list, paragraphs, links and so on. The good news is that the toolbar can be extended and customized to your needs, which is great, especially when it comes to using specific styles.
Conditions are supported. They are set as style “attributes”; that is, you can define the audience, status, etc… for your content.
You can filter the preview by audience and products. I still need to find out how to filter by version.
Creating content from scratch is very easy. You can select what kind of content you’d like to create from a list of templates. If you select DITA topic, you can also select the template you want to base your topic on: topic, task, content, reference or ditaval. Additionally, you can create “custom templates” for, for example, subject-matter experts who are not familiar with DITA but would like to add some information to the documentation. You can send them an e-mail containing a task to create documentation for a particular topic. They don’t see the DITA format, but a very intuitive user interface similar to Word.
The content of snippets in MadCap Flare is also valid for AEM. In AEM, this concept can be set as conrefs or keys.“Snippets” don’t have a different format in AEM, all the topics are .xml, but the type of element that can be re-used is p (not topic). Reused content is displayed in blue. (<p conref=”link”></p>)
Topics cannot be inserted as weblinks, but only as content reference. This prevents a lot of problems while moving & renaming concepts, because xrefs are always updated.
You can also create e-mail links.
You can set language properties to identify the language in which the topic is written.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s