General Guidelines and Information

SAP HANA

Link Placement

As a general rule, don't use inline links

The use of inline links is strongly discouraged. Inline links are links that appear in the body of a topic rather than in the Related Information section of the topic. They are best avoided for the following reasons:

Maximum flexibility for reuse is required, both now and in the future. We need to be able to slice and dice content to support things like:
• Different product flavors
• Evolving mix of components that make up SAP HANA (Cloud)
• Integration scenarios of SAP HANA (Cloud) components with other products, components, and services
Minimum user disruption: Users who are in the middle of learning or doing should generally not be distracted or encouraged to leave content.
Consistency: The navigational standard throughout SAP documentation is to have links in the Related Information section.

Of course, in some content types or if you consciously want to encourage the user to leave your content, in-line links may be appropriate. See the guideline Use inline links where and where warranted.

Include one or more of the following links in the Related Information section.

Key references to topics in the same buildable map or other buildable maps that support O2O linking
External web links to topics in other buildable maps because O2O links are not technically possible
• Use <linktext> to provide the name of the target topic exactly. Disambiguation information may be put in parenthesis, for example, you could include the name of the target guide, tool, or product.
• Get the topic URL from the production version of the target deliverable.
▪ If there is no production version (yet), the link will not work.
▪ For testing, wait until a test production docset has been published.
▪ Remember to replace the version name or number with "latest"
• Test external links before publication as they are error prone. Look out for the following:
▪ Changed titles not reflected in the link text
▪ Wrong version in the URL (link to on-premise/cloud, not using latest, using DRAFT accidentally)
▪ Missing link text
External web links to resources on SAP web sites or links to non-SAP Web sites
• Use <linktext> for the names of web sites, and so on.
Links to SAP Notes
• Use <desc> to add the title of the note (visible on mouse-over)

To make link lists easier to consume, you may use the <linklist> element with <title> for example to separate out a long link list into sections (but try to avoid long link lists)

false

Examples

<linktext>Design-time Content Compatibility (SAP HANA Cloud Migration Guide)</>

<linktext>User and Role Management (SAP HANA Cockpit)</>

<linktext>Key Management Service (SAP Data Custodian)</>

Use inline links where and when warranted

Inline links make sense in some cases. in particular:

In topics that serve to orient users within the product or the documentation. Users refer to such topics in order to figure out where to go to find out more about something. Typical examples:
• Feature or product overview topics
• Workflow overview topics
• API reference topics
• Resource overview topics
• What's New topics

false

Examples

If you want to encourage the user read to leave the topic without having read to the end of the topic (yet). For example:
• The user must understand or complete a vital prerequisite before preceding.
• A particular task in a procedure is documented in a separate detailed procedure.

false

Examples

Migrate an SAP HANA Service Database to SAP HANA Cloud

In-line links to an element within the same topic (in-topic links) can be used in long topics to help navigation within the topic

false

Examples

When inserting an inline link, do so using a standard cross-reference formulation ("For more information, see...", "See", etc.) at the end of the sentence, paragraph, section or other natural break in the text.

guideline

TIPWhen deciding whether to use an in-line link, ask yourself:"Are text flow and comprehensibility negatively affected if the inline link is omitted or moved to the end of the topic?" (Cross-References and Hyperlinks)

Map Hierarchy Links

Map hierarchy links are links that are automatically included in topics based on a map configuration. It means you don't have to set the links manually in each topic.

warning

NOTEHierarchy links set in the project map apply to all outputs and are therefore part of the overall linking strategy of a product/component/application. They are managed by the doc lead.

You may want to configure hierarchy links for individual topics in the following situations, for example:

In topics that serve to group other topics but otherwise have little content (typical in reference documentation)
In process overview topics when you want to show the sequence the user will take that also includes the short description to describe what’s in the step

false

Examples

In topics that also have manually set related links, map hierarchy links could be distracting or confusing.

Follow the general recommendation and always consider whether a link is really necessary. What is the added value of the link for the reader? What if it is omitted?

Inline Cross-References

Use inline cross references in the topic body sparingly

For some links in the Related Information section, you may want to add a corresponding textual cross-reference in the topic body. However, do so , for example, in a vital prerequisite.

Use one of the recommended formulations

These are the recommended formulations patterns for inline cross-references:

For more information, see the <cite>SAP HANA Security Guide</cite>.
For more information about xyz, see the <cite>SAP HANA Security Guide</cite>.
For more information, see the section on xyz in the <cite>SAP HANA Server Installation and Update Guide<cite>.

The following formulation patterns are because the navigational standard throughout SAP documentation is to look here for more information:

For more information, see <cite>Related Information</cite>.
For more information about xyz, see <cite>Related Information</cite>.
For more information about xyz, see the related links.

The following formulation pattern because a topic title may change, so you will need to check it before every new release of the documentation:

For more information, see <cite>topic title</> in the <cite>guide title</>.

Links to Entire Guides

Provide a link to the root topic

If you want to link to another deliverable (not a specific topic), then set a link to the “root topic” of the target deliverable, either as an O2O link or an external web link.

The first topic in a buildable map is known as the “root topic” because it acts as a root node and entry point when the user accesses the deliverable from another document.

Before linking to a root topic, check that it meets the following prerequisites:

The topic title is the same as the title of the deliverable itself.
The topic content reflects the topic title (that is it provides a meaningful introduction to the deliverable).
The topic does not have any profiling at topic level (it may still contain profiling on element level).