Public Let’s Exploit DITA: How to automate an App CatalogSpecialized DITA maps define keys and connect them to files in the CMS All references to reused content use the @conkeyref

Let’s Exploit DITA: How to automate an App Catalog

Carsten Brennecke, SAPApril 05, 2016

Public

© 2016 SAP SE or an SAP affiliate company. All rights reserved. 2Public

Agenda

Our Challenge

Our DITA Landscape

Our Approach

Conclusion

Our Challenge


What Is An App Catalogue?

As part of SAP’s software delivery we are providing a number of SAP Fiori Apps for various SAP products. The customer needs an overview of these apps with various information:

What is the app about

What has changed over time

How to implement the app

How to extend the app

On the SAP Help Portal this information is provided in one delivery containing information for all available apps.


The Needed App Information

Each app documentation should look the same:

Same structure in map and topics

Same standard texts for standard features

Show information from central systems

And the customer should find his app easily


But the Reality Was

Authors were creative in changing the template structure

Authors added new topics

Data copied in from systems got outdated

Central changes of standard texts were not implemented

New apps didn’t show up in the overview table or at the wrong place

…

Our DITA Landscape


Our DITA Landscape

We are using a DITA CMS with fully key-based approach:

All objects referenced by keys in maps (<topicref>) and links (<xref> and <link>) (instead of direct file names)

Specialized DITA maps define keys and connect them to files in the CMS

All references to reused content use the @conkeyref attribute

The build process is owned by SAP using the DITA OTK.

Our Approach


Ideas to Improve

Author should not need to maintain the map

Author should only create content that is app-specific

Central info architect maintains central content

For a new app the creation of DITA objects should be as automatic as possible

Author should only need to maintain the app in new release versions if the app has changed

Customer should find the app in a central table with easy filtering options


Approach: Use Reuse Topics for Central Content

Content that should be identical in all documentation for relevant apps is maintained in referable content objects by the central information architect

Content is maintained centrally – all changes are automatically used for all apps


Approach: Use Templates

Templates are available for both the sub-map and all needed topics. Authors create a sub-map for their new app documentation and all needed topics are created template-based too.The referable content objects are included into the sub-map with the attribute“processing-role=resource-only”


Approach: Use Separate Topic for Author’s Work 1/2)

Use an “App Details” topic for authors to create app-specific content. This topic is structured in a way to allow the author to easily enter the needed app-specific content:

Topic refers to standard texts where needed

Topic refers to system data where needed

Author only adds app-specific content Author only maintains one topic If no app-specific changes needed,

author does not need to touch it


Approach: Use Separate Topic for Author’s Work (2/2)


Approach: Provide Selection Fields for Author (1/2)

Each app can support different standard features. To ensure the correct features are shown in the app documentation, the standard feature content is profiled. Authors can select the relevant features by selecting a checkbox.

Each selectable DITA element is profiled

Based on this profile a style sheet shows a selection box

Based on the box selection, the profiling value is set to “yes” or “no”

In the build’s ditaval file, “fiori_text_include” is set to “yes”


Approach: Provide Selection Fields for Author (2/2)

The author’s view of the “App Details” topic. Individual features or a complete feature block can be selected:


Approach: Import System Data

The app documentation needs to contain content that is originally maintained in a different system.

Based on metadata the needed values are imported

The ID is defined by the author in the “App Details” topic

Necessary metadata is defined in the system topic or in the build data

Author does not need to copy in values manually

Values are always up-to-date


Approach: App Documentation Created Automatically

The actual app documentation contains of three topics.

All topics are created by including content out of the “app details” topic, the “system” topic and some central topics.


Example of Resulting Topic

You can find this example on the SAP Help Portal with this link


The Picture So Far

App documentation

Reused in

Reused in

Reused inApp Details

System data

Central content overview

history

implement

extend

Info architect

Authors


Approach: Create Dynamic Table to Find Your App (1/3)

Each system topic contains a row with references to the overview information of this app.

The catalog row contains a link to the overview topic and references to some system data.



Each map for a product contains a topic with a table referencing all catalog rows.

The first and last row of this table has an ID and new rows need to be added in between.



The overall delivery contains a catalog table referencing all product catalog tables.

In the DITA source additional coding is added to allow it to be displayed as dynamic table

In the HTML output this table is shown as dynamic table with JavaScript-based options like filtering and searching.


Resulting Dynamic HTML Table

The resulting table allows automatic sorting, filtering, and searching.

All apps are automatically sorted by name

The user can filter by search on the app name

The user can filter by dropdown list on the other columns


Which Initial Manual Steps Are Needed?

To document a new app, the author needs to:

Create the map based on the template and create the topics based on their templates

Replace the references to the “app details” topic and the “system” topic with their correct value

Replace the reference the “app description topic” in the catalog row

Include the row for the catalog table into the product-specific table

Enter the app-specific data into the “app details” topic


Automation of Creation

By an XSLT script we automated the process for the author:

1. The author starts the sub-map creation and enters the app name The system creates the sub-map and the topics within the sub-map The system updates the references to the “app details” and “system” topic within all created topics The system changes the names of the created topics to include the app name where needed

2. The author adds the catalog table row to the product-specific table

Conclusion


Conclusion

DITA supports you ideally to create highly standardized documentation

Content experts can easily add their knowledge to the documentation

DITA allows to enhance the content with system data

The authoring process can be automated effectively

Thank you Contact information:

Carsten BrenneckeKnowledge ArchitectSAP SEm: [email protected]


© 2016 SAP SE or an SAP affiliate company. All rights reserved.

No part of this publication may be reproduced or transmitted in any form or for any purpose without the express permission of SAP SE or an SAP affiliate company.

SAP and other SAP products and services mentioned herein as well as their respective logos are trademarks or registered trademarks of SAP SE (or an SAP affiliate company) in Germany and other countries. Please see http://global12.sap.com/corporate-en/legal/copyright/index.epx for additional trademark information and notices.

Some software products marketed by SAP SE and its distributors contain proprietary software components of other software vendors.

National product specifications may vary.

These materials are provided by SAP SE or an SAP affiliate company for informational purposes only, without representation or warranty of any kind, and SAP SE or its affiliated companies shall not be liable for errors or omissions with respect to the materials. The only warranties for SAP SE or SAP affiliate company products and services are those that are set forth in the express warranty statements accompanying such products and services, if any. Nothing herein should be construed as constituting an additional warranty.

In particular, SAP SE or its affiliated companies have no obligation to pursue any course of business outlined in this document or any related presentation, or to develop or release any functionality mentioned therein. This document, or any related presentation, and SAP SE’s or its affiliated companies’ strategy and possible future developments, products, and/or platform directions and functionality are all subject to change and may be changed by SAP SE or its affiliated companies at any time for any reason without notice. The information in this document is not a commitment, promise, or legal obligation to deliver any material, code, or functionality. All forward-looking statements are subject to various risks and uncertainties that could cause actual results to differ materially from expectations. Readers are cautioned not to place undue reliance on these forward-looking statements, which speak only as of their dates, and they should not be relied upon in making purchasing decisions.

Documents

Public Let’s Exploit DITA: How to automate an App CatalogSpecialized DITA maps define keys and connect them to files in the CMS All references to reused content use the @conkeyref