Introduction

Follow the guidelines below to make sure that your DITA content is consistent and of high-quality.

<div> <div>Guidelines</div> <div>Description</div> </div> <div> <div>Navigation Structure</div> <div> <p>Follow the guidelines for topic titles and structuring your navigation.</p> <p>See <a href="https%3A%2F%2Fwww.sap.com%2Fr%2F2KnNFFlnhpwDi9_S82mCDNyMzyw8WIRXRMfojlt-GPU">Navigation Structure</a>.</p> </div> </div> <div> <div>Topic Structure</div> <div> <p>Structure your topic based on the respective topic type.</p> <p>See <a href="https%3A%2F%2Fwww.sap.com%2Fr%2FkGwY2oTzq1L8EUYAws5siwkfduuU8YsFLA6KKKs5bsg">Topic Structure</a>.</p> </div> </div> <div> <div>Easy to Scan</div> <div> <p>Write short paragraphs and sentences; use subheadings, (un)ordered lists, and emphases to make users able to easily scan big chunks of content. Avoid redundant words or phrases and obvious statements in accordance to your users.</p> <p>See <a href="https%3A%2F%2Fwww.sap.com%2Fr%2FWvIfXLgHlLU_axO9z-iTdQ-3lin-m_zkAdQ63PkqC7Q">Make Topics Easy to Scan</a>.</p> </div> </div> <div> <div>PCA</div> <div> <p>Use PCA language. Discuss with your PO and PM which types of deliveries are the most appropriate for your users.</p> <p>See <a href="https%3A%2F%2Fwww.sap.com%2Fr%2F45BBBMmHMo7g5JvE2y8i6lHTU7pM3Kpj1UHlreSKtF0">People-Centric Approach</a>.</p> </div> </div> <div> <div>Content Validation</div> <div> <ul> <li>Always check your content with Acrolinx before you release it.</li> <li>Always send your new content or significant changes in existing content for editing.</li> </ul> <p>See <a href="https%3A%2F%2Fwww.sap.com%2Fr%2FOOAqmWy2FxwyiiQmTZrLZqFipm3iWi_NCeu3Oor5whE">Validating Your Content</a>.</p> </div> </div>

Topic Titles

<div> <div>Topic Type</div> <div>Rule</div> <div>Example</div> </div> <div> <div> <p>Task overview</p> <p>Complex task (chunked task topics with two or more separate procedures)</p> </div> <div> <p>Gerund phrase</p> <p>For chunked task topics, use:</p> <ul> <li>A gerund phrase for the main heading</li> <li>An imperative verb phrase for the headings of the different procedures</li> </ul> </div> <div></div> </div> <div> <div>Task</div> <div>Imperative verb phrase</div> <div></div> </div> <div> <div> <p>Concept (not a task overview)</p> <p>Reference</p> </div> <div>Noun phrase</div> <div></div> </div>

Structuring Your Navigation

Arrange the structure logically. Restructure the navigation trees to group content that’s connected and to make them as visually similar as possible. Arrange related content sections successively.

For example, Solutions followed by .

Topic Structure

<div> <div></div> <div>Task</div> <div> <p>Overview topics</p> <p>Complex task topics</p> </div> <div>Concept</div> <div>Reference</div> </div> <div> <div></div> <div>Imperative verb phrase</div> <div> <p>Gerund verb phrase</p> <p>(Imperative verb phrase for subheadings inside complex task topics)</p> </div> <div>Noun phrase</div> <div>Noun phrase</div> </div> <div> <div></div> <div>Required in all topics. A good summary right up front makes it easy for the users to scan the documentation and quickly know if they need to read the topic.</div> <div>Required in all topics. A good summary right up front makes it easy for the users to scan the documentation and quickly know if they need to read the topic.</div> <div>Required in all topics. A good summary right up front makes it easy for the users to scan the documentation and quickly know if they need to read the topic.</div> <div>Required in all topics. A good summary right up front makes it easy for the users to scan the documentation and quickly know if they need to read the topic.</div> </div> <div> <div><strong>Content</strong></div> <div> <p>Use same words or phrases for the same type of information.</p> <p>Make sure the procedures steps follow a clear sequence.</p> </div> <div> <p>Use same words or phrases for the same type of information.</p> <p>Use similar way of structuring information in overview topics.</p> </div> <div> <p>Use same words or phrases for the same type of information.</p> <p>If a concept topic is too complex, divide the information into few short and simple concept topics.</p> </div> <div>Use same words or phrases for the same type of information.</div> </div>
warning
Please make sure your procedures' steps follow a clear sequence. For example, in this topic, steps 3 to 8 describe different options, and subsequent numbering is not appropriate.
warning
There are some generic DITA topics in our buildable maps, as well as concept topics that contain procedures. Please rework such topics to their relevant type. You can use the following guidelines for changing a topic type: Changing the Type of a Migrated Topic.

Make Topics Easy to Scan

In the topic content, use:

<div> <div>Description</div> <div>Recommended</div> </div> <div> <div>Clicking a link for more details</div> <div> <p>For more information, see…</p> <p>For more information about…, see…</p> </div> </div> <div> <div>Optional descriptions</div> <div>Optional:</div> </div> <div> <div>Right Clicking</div> <div>In the context menu of the page/file, choose…</div> </div>
warning

Please avoid:

  • Redundant words or phrases
  • Obvious statements

Validating Your Content

Acrolinx

Use Acrolinx to verify your content. The SAP rules in Acrolinx are based on the SAP Style Guide for Technical Communication, mainly things from the Style and Wording main chapter. Acrolinx now even comes with different flavors like Brand Voice and PCA.

Note that not every rule in the SAP Style Guide can be checked by Acrolinx. Acrolinx checks formal aspects such as how many passives or overlong sentences. But obviously it can’t check the semantics, for example if some content is meaningful or if some content is stating the obvious.

Acrolinx also checks spelling and grammar so it's a great way to catch mistakes.

See Getting Started with Acrolinx.

Editing Service

Always send your new content or significant changes in existing content for editing. See Language Editing.