Task-Oriented Structured Writing

Product Specifics / SAP HANA Cloud

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

Provide clear and consistent structures by distinguishing topic types by their titles as follows:

<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

Provide clear, comprehensive, consistent content structures by separating information types as follows:

<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

Present topic types in clear patterns, making tasks as prominent as possible.

Example:

🔵 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