Successfully reported this slideshow.
We use your LinkedIn profile and activity data to personalize ads and to show you more relevant ads. You can change your ad preferences anytime.

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

111 views

Published on

How to describe information about software applications for customers and developers using DITA XML. Examines a successful approach that ensures that technical writers only need to create content that is app-specific, ensuring that the creation of DITA objects are automated as much as possible, while still focusing on the needs of customers to easily find the information they are looking for.

Originally presented by Carsten Brennecke at the DITA North America 2016 conference. Thanks also to CIDM!

Published in: Technology
  • DOWNLOAD FULL BOOKS, INTO AVAILABLE FORMAT ......................................................................................................................... ......................................................................................................................... ,DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... ,DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... ,DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... ,DOWNLOAD FULL. PDF EBOOK here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... ,DOWNLOAD FULL. EPUB Ebook here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... ,DOWNLOAD FULL. doc Ebook here { https://tinyurl.com/yyxo9sk7 } ......................................................................................................................... ......................................................................................................................... ......................................................................................................................... .............. Browse by Genre Available eBooks ......................................................................................................................... Art, Biography, Business, Chick Lit, Children's, Christian, Classics, Comics, Contemporary, Cookbooks, Crime, Ebooks, Fantasy, Fiction, Graphic Novels, Historical Fiction, History, Horror, Humor And Comedy, Manga, Memoir, Music, Mystery, Non Fiction, Paranormal, Philosophy, Poetry, Psychology, Religion, Romance, Science, Science Fiction, Self Help, Suspense, Spirituality, Sports, Thriller, Travel, Young Adult,
       Reply 
    Are you sure you want to  Yes  No
    Your message goes here
  • Be the first to like this

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

  1. 1. Let’s Exploit DITA: How to automate an App Catalog Carsten Brennecke, SAP April 05, 2016 Public
  2. 2. © 2016 SAP SE or an SAP affiliate company. All rights reserved. 2Public Agenda  Our Challenge  Our DITA Landscape  Our Approach  Conclusion
  3. 3. Our Challenge
  4. 4. © 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.
  5. 5. © 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
  6. 6. © 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  …
  7. 7. Our DITA Landscape
  8. 8. © 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.
  9. 9. Our Approach
  10. 10. © 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
  11. 11. © 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
  12. 12. © 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”
  13. 13. © 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
  14. 14. © 2016 SAP SE or an SAP affiliate company. All rights reserved. 14Public Approach: Use Separate Topic for Author’s Work (2/2)
  15. 15. © 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”
  16. 16. © 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:
  17. 17. © 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
  18. 18. © 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.
  19. 19. © 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
  20. 20. © 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
  21. 21. © 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.
  22. 22. © 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.
  23. 23. © 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.
  24. 24. © 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
  25. 25. © 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
  26. 26. © 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
  27. 27. Conclusion
  28. 28. © 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
  29. 29. Thank you Contact information: Carsten Brennecke Knowledge Architect SAP SE m: carsten.brennecke@sap.com
  30. 30. © 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.

×