Let s Exploit DITA: How to automate an App Catalog

Let s Exploit DITA: How to automate an App Catalog Public Carsten Brennecke, SAP April 05, 2016

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. 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 4

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 5

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 6

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. 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 8

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 10

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 11

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 12

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 13

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 15

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: 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 16

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 17

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. 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 18

The Picture So Far Info architect Central content Authors App documentation overview history Reused in App Details Reused in implement extend System data Reused in 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 20

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. 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 21

Approach: Create Dynamic Table to Find Your App (2/3) 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. 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 22

Approach: Create Dynamic Table to Find Your App (3/3) 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. 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 23

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 24

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 25

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 26

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 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 28

Thank you Contact information: Carsten Brennecke Knowledge Architect SAP SE m: carsten.brennecke@sap.com

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 forwardlooking 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. 2016 SAP SE or an SAP affiliate company. All rights reserved. Public 30