Article-Based Help
Product Specifics / SAP Analytics Cloud
Introduction
SAP Analytics Cloud’s approach to documentation is designed to maximize the findability and usability of help content. It does this by providing a relatively flat hierarchy of categories and subcategories that are based on user goals, personas, and expectations, rather than on how the related features are presented in the interface. Content is organized from simplest to most complex, with content that applies to all users and casual users at the top of the navigation structure and more niche content that applies to smaller user groups at the bottom.
Each article contains all the information a specific type of user might need to complete a standalone goal. Articles are written with the aim of getting users to experience success as quickly as possible by focusing first on the core concepts and tasks, and then providing the option to dig deeper into edge cases and more detailed content if necessary. Introductory articles are provided within each category to support users who are new to SAP Analytics Cloud.
Categories, subcategories, articles, and reference topics use consistent naming conventions based on plain language to optimize searching and browsing.
Navigation
Navigation within the Table of Contents is designed to be simple and transparent, with all articles organized by category and subcategory.
Scope
Categories represent collections of related goals for specific personas or groups of users. They are not constrained by how the features that support completing those goals are organized in the interface. For example, the “Planning” category encompasses multiple modules in SAP Analytics Cloud, such as Allocations, Value Driver Trees, Data Actions, Calendar, etc.
Under each category, content is logically grouped into subcategories to keep the full list of articles from overwhelming users. The first subcategory in each category is “Getting Started with <Category Name>,” which contains articles that assist new users to orient themselves to the collection of features associated with the higher-level goals; experienced users can skip over this content.
Each category has a landing page where users can see all content for that collection of goals in one location; subcategories are used purely for grouping purposes and do not have associated landing pages. Category landing pages contain minimal information – a brief description of who the target user is and what the category can enable that user to achieve, along with a list of links to the articles that belong in that category, grouped by subcategory. Image maps are also acceptable, provided they follow visual guidelines (refer to the Diagrams and Image Maps section for details).
Content in the Table of Contents and on the landing pages is organized as if the user is intended to read each article in order, although the article content itself does not rely on previous or following articles to be understood.
Naming Conventions
For both categories and subcategories, industry-standard terminology is used in favor of proprietary terms. All names are in title case.
Category names:
- Use the simplest noun or noun phrase available.
- Make it obvious which persona(s) the category applies to.
- Are as short as possible.
Examples include “Content Viewing and Personalization,” “Data Visualization (Stories),” “Planning,” “System Administration.”
Subcategory names:
- Use a phrase starting with a gerund to frame the subcategory as something active.
- Are as long as required to assist navigation.
Examples include “Getting Started with Planning,” “Planning with Value Driver Trees,” “Setting Up Allocations to Split Values.”
Implementation
In Ixiasoft:
- A submap exists for each major category.
- Each submap (modified using the Oxygen DITA Map Editor) defines a <topichead> element for each subcategory that displays as a twist-down option in the Table of Contents.
- Landing pages exist as Concept-type topics with sections for each subcategory.
- In each subcategory section, articles are presented in an unordered list of xref links.
Articles
An article is a help document that provides all the conceptual and procedural information a user would need to accomplish a specific standalone goal.
Article Pattern
This Article Pattern is available for use as a template (loiob147c1ec68e344118e919f5df601330f).
Scope
As opposed to topics, which can be fragments of content, articles are written to be understood by users without any additional context or information. The writing style within the article focuses on assisting the user, not marketing the product features; “why?” is as important as “what?” and “how?”
Articles focus on content that adds value to users and aids in comprehension and retention, such as examples of where and how to use certain features, diagrams that show relationships, and so on.
The length of the article is determined by the goal itself, but different techniques are used to ensure the article hits the sweet spot in terms of amount of content – neither so long that it feels overwhelming to users, nor so short that it feels unrewarding:
- For large goals or deliverables that have infinite variations, the goal is defined with a narrower scope. For example, “Create Your First Story” instead of “Create a Story.”
- For goals that have simple and more complex variations on the same theme, content is divided into basic and advanced articles. For example, “Set Up Your First Allocation Process” and “Build an Advanced Allocation Process.”
- For goals that may need very detailed or technical information to complete, such as configuring settings or building formulas, the detailed content is presented in compact formats such as tables and matrices. Refer to the Tables section for more information.
Naming Conventions
Introductory and purely conceptual articles use the standard construction of “About <Topic>.”
How-to article names:
- Use the root form of the verb to finish the question “How Do You…?”
- Contain relevant keywords when appropriate.
- Are as complete as possible to help with searching.
- Use plain language to supplement proprietary terms that are not well understood.
- Use “You/Your” where appropriate.
- Use plurals for objects, unless the object is a collective noun.
Examples include “Log In for the First Time” and “Edit Your Profile.”
Implementation
In Ixiasoft, articles are constructed using the Concept type of topic, with <concept> and <task> elements nested inside the main <concept> element.
Existing Links
Some articles are linked within the SAP Analytics Cloud interface or in blogs and other related content. When changes are made that result in a document and its associated LOIO being removed from the Help, the following precautions are taken:
First, the author checks whether the LOIO is linked to any other sites. The following resources are available:
- LOIO Identifiers (in-app Help links)
- Modules (Nav Labels + URLs, Empty State Texts, and Help Center Links), Page 6
- LOIOs for Guided Tips and SAC Website (in-app Guided Page Tips links)
- Guided Playlists (contacts: Jessica Gutierrez)
- SAP Support Guided Customer Help Tree (contact: John Leggio)
- SAC Help Portal Product page (contact: Sean McGregor)
If the LOIO is used within the interface, the author re-uses the LOIO for the appropriate article; if it is used in any other source, every effort is made to do the same. The topic type is changed, if required, in the text view in Oxygen. For start pages (empty state) in the Modules layout, links are to the launch pages for the appropriate L1 category.
If the LOIO cannot be re-used, the author communicates directly with the owner of the web site (Guided Playlists, Support, Help Portal), so that the link can be updated to the appropriate article. The author also informs the appropriate UA lead, who then submits a URL redirect request with the help portal team so that customers are redirected to this page:
Sorry, we can’t find the page you’re looking for
Each article contains the following elements:
Short Description
The <shortdesc> element provides a brief (1-2 sentences maximum) summary of the target user and goal/use case for the article (i.e., a kind of “YOU ARE HERE” pointer or tl;dr). The most critical information to orient the user is in the first 160 characters so that users can confirm that their search or navigation has brought them to the correct article.
Example Short Description in the CCMS
The short description:
- Expresses the contents, benefits, and value of the complete article.
- Includes the product name and the relevant role, if applicable.
- Includes high-priority keywords to improve search results.
- Contains fewer than 50 words in only one or two sentences.
- Uses complete sentences.
- Does not restate the title or state the obvious.
- Does not start with “This article….”
Intro Concept
An introductory concept in the article provides context about the goal covered by the article and any information users need to know before they start, such as definitions, prerequisites, examples, etc.
Concepts and Tasks
Additional concepts and tasks are provided to assist the user to complete the stated goal, presented in whatever order makes the most sense to the flow.
Optional Elements
The following optional elements are included in articles as appropriate:
Tables
Whenever possible, information is presented in table format, which enables users to quickly scan for the information they need. If the content runs more than 10-15 rows, it is displayed in a data table, which supports searching, sorting, filtering by category, and pagination. Refer to The DataTable (a dynamic table) in the UA Infrastructure User Guide for details.
Diagrams and Image Maps
Key concepts are presented visually to reinforce learning. All diagrams follow branding guidelines to present a cohesive look across articles. The guidelines, templates, and examples are provided in the file:
There's also a Figma version of the guidelines and templates. For access, please contact Joanna Denford at joanna.denford@sap.com.
Example of a process workflow diagram - one of many types of diagrams available in the templates.
Where appropriate, diagrams are presented as image maps that enable users to jump to more detailed content within the Help. Refer to Image Maps in the UA Infrastructure User Guide for details.
Example of an image map diagram.
Screenshots
Users heavily favour the inclusion of screenshots on the documentation, as they help provide context when users are confused or overwhelmed by either the product or the written explanation.
However, screenshots pose a unique challenge in documentation both because it is difficult to translate them into multiple languages and because they can become obsolete or misleading as the product evolves.
If you choose to include screenshots in your articles, consider the following options to minimize the impact of changes to the interface on the maintenance of these screenshots.
Is the content the point?
Use a partial screenshot of only the relevant content. For example, if you are illustrating how data changes before and after users perform actions, screenshots should focus on the data itself, rather than on the whole interface or the widget in which the data is contained. Refer to the diagram guidelines found in the Diagrams and Image Maps section above for details on how to size, format, and annotate screenshots.
Is the UI the point?
Use a Simplified User Interface (SUI) image. For example, if you want to orient users to the layout of a feature in the product, this is the preferred option. SUIs show only the elements (including text) that are absolutely required to follow the steps in a transaction or to locate the feature in the interface and reduce all other elements on the page to simple shapes.
To use a SUI in your article, choose one of the following formats:
- Screenshot SUI – This uses an actual screenshot of the product, over which shapes are layered to hide text that does not need to be displayed. Refer to the diagram guidelines to construct the SUI in PowerPoint (see above) or Figma, depending on which tool you are most comfortable using. Note that the original instructions on creating a SUI using Snagit do not follow the new Fiori Horizon design guidelines, but you can still use this approach if you prefer.
Screenshot SUI
- Graphic SUI – This is a SUI constructed from scratch in Figma. This style leans a bit more into the Fiori Horizon design and is a good choice if you want to add extra visual appeal to overview topics. You can reach out to Joanna Denford in the UA Design Services team to have this type of SUI created for you or to learn how to create them for yourself.
In either style, the SUI can be the full window or cropped to focus on a specific element in the interface. If you create the SUIs yourself, feel free to reach out to the UA-DS team for a quality check (joanna.denford@sap.com).
Videos
If a video has been created for the subject matter covered in the article, the video can be added as reusable content. Each video is stored in a referrable-content topic so that it can be single-sourced in multiple locations. The video is added to the article in a concept element as a conkeyref using the following code: <conbody conkeyref="loio7cd1d4946e254cd39a6fd86200b488ab/{conbody_ID}"/>. The conbody contains the title and description in draft comment for reference, along with an embed of the YouTube player and a link to the Media Share version (for markets where YouTube is restricted).
Videos can be added at any point in the flow of an article.
Related Links
An optional section provides links to other articles that do not fall within the current category but are closely related. The <related-links> element is located in the last nested concept or task in the main topic. Note that future work is planned to use relationship tables to manage these links.