Upload
oasis-dita-adoption-tc
View
30
Download
1
Embed Size (px)
Citation preview
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
© 2016 SAP SE or an SAP affiliate company. All rights reserved. 4Public
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. 5Public
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. 6Public
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
© 2016 SAP SE or an SAP affiliate company. All rights reserved. 8Public
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
© 2016 SAP SE or an SAP affiliate company. All rights reserved. 10Public
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. 11Public
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. 12Public
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. 13Public
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. 14Public
Approach: Use Separate Topic for Author’s Work (2/2)
© 2016 SAP SE or an SAP affiliate company. All rights reserved. 15Public
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. 16Public
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. 17Public
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. 18Public
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. 19Public
Example of Resulting Topic
You can find this example on the SAP Help Portal with this link
© 2016 SAP SE or an SAP affiliate company. All rights reserved. 20Public
The Picture So Far
App documentation
Reused in
Reused in
Reused inApp Details
System data
Central content overview
history
implement
extend
Info architect
Authors
© 2016 SAP SE or an SAP affiliate company. All rights reserved. 21Public
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. 22Public
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. 23Public
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. 24Public
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. 25Public
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. 26Public
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
© 2016 SAP SE or an SAP affiliate company. All rights reserved. 28Public
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. 30Public
© 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.