General Information and Guidelines

A task-oriented writing approach is best practice for documentation that explains how to use the software.It is supported by the DITA architecture.

Task Orientation in SAP HANA "How To" Documentation

Topic Titles

<div> <div>Topic Type</div> <div>Contents</div> <div>Title Style</div> <div>Examples</div> </div> <div> <div>🔵 Overview, Introduction</div> <div>General/Process</div> <div>Gerund</div> <div> <p>Configuring Application Access</p> <p>Mapping Host Names for Database Client Access</p> </div> </div> <div> <div>🟢 Tasks</div> <div> <p>Procedure</p> <p>Tutorial</p> </div> <div>Imperative verb</div> <div> <p>Enable Access to an Application</p> <p>Create a Delivery Unit</p> </div> </div> <div> <div>🔴 Concepts</div> <div>Background</div> <div>Noun phrase</div> <div> <p>Application Access</p> <p>The Application Privileges File</p> </div> </div> <div> <div>🟡 Reference</div> <div>Details</div> <div>Noun phrase</div> <div> <p>Application Access Configuration Options</p> <p>URL Rewrite Rules</p> </div> </div>

Info Typing

<div> <div>Topic Type</div> <div>Contents</div> <div>Examples/Suggestions</div> </div> <div> <div>🔵 Overview, Introduction</div> <div>General/Process</div> <div> <ul> <li>High-level description</li> <li>Process (several procedures)</li> </ul> </div> </div> <div> <div>🟢 Tasks</div> <div> <p>Procedure</p> <p>Tutorial</p> </div> <div> <ul> <li>Context/prerequisites</li> <li>Steps</li> <li>Steps with code examples</li> </ul> </div> </div> <div> <div>🔴 Concepts</div> <div>Background</div> <div> <ul> <li>What is it?</li> <li>What does it do?</li> <li>Why do I need it? Where does it fit in?</li> </ul> </div> </div> <div> <div>🟡 Reference</div> <div>Detailed options</div> <div> <ul> <li><a href="https%3A%2F%2Fhelp.sap.com%2Fviewer%2FDRAFT%2F4505d0bdaf4948449b7f7379d24d0f0d%2F2.0.05%2Fen-US%2F809a42308d814b7ea1c8369e55591515.html">Command syntax overview</a></li> <li><a href="https%3A%2F%2Fhelp.sap.com%2Fviewer%2FDRAFT%2F4505d0bdaf4948449b7f7379d24d0f0d%2F2.0.05%2Fen-US%2Fd7515916796140f9801f133909c71440.html">Parameters/Options</a> (table/lists)</li> <li><a href="https%3A%2F%2Fhelp.sap.com%2Fviewer%2FDRAFT%2F4505d0bdaf4948449b7f7379d24d0f0d%2F2.0.05%2Fen-US%2F4d137d5f2ff2410bbc2bb4892351ba11.html%23loio4d137d5f2ff2410bbc2bb4892351ba11__section_y4p_2ry_xr">Parameter/Option Syntax</a>(+ examples)</li> </ul> </div> </div>

Structure

Example:

Image

🔵 Configuring Application Access (overview/complex task)

🟢 Tasks

  • Create an Application Descriptor
  • Enable Access to an Application
  • Create an Application Privileges File

🔴 Concepts

  • XS Application Descriptors
  • The Application Access File
  • The Application Privileges File

🟡 References

  • Application-Access Keyword Options
  • Application-Access Rewrite Rules

More Information

For more detailed explanations and examples, see SAP HANA Developer Docs: DITA Core Architecture Roadmap