Editorial guidance for Experience League

A concept is about the what and the why you use a feature. It describes what your reader can accomplish using Experience Cloud applications. Concepts are introductions, overviews, and most blogs. A concept always precedes one or more tasks.

For headings, TOC entries, and SEO elements, use nouns and noun phrases for concepts. Examples:

• Processing options in Analytics
• Campaign integrations
• Audience services

A task is the how. It teaches how to accomplish a goal and typically includes steps. Associate your tasks headings and steps with active verbs.

• Get started with processing options
• Create a Target activity
• Run a Page Views report

Each task, regardless of length and scope, must have a preceding concept. That concept can be a parent heading or page.

Headings serve as both the structural outline of your page and a point of reference for readers when scanning content. Scanning becomes easier when you use headings to break content into natural, digestible chunks of information.

Headings must make sense when viewed in search results, snippets, popovers, TOCs, and so on. The following editorial guidance ensures that headings work in every situation.

Subheadings let you break up large chunks of information into scannable chunks. They are level two (H2) or three (H3) headings. They are the structural outline of your page and a point of reference for readers when scanning content.

Subheads follow the same editorial guidelines as H1s (see previous section).

• Prerequisites
• Before you begin
• What you will learn
• More help on this topic

Common structural examples for concepts and tasks.

Multipage

TOCs used to strictly separate information based on content types:

• Concept (parent page)

  • Task (child page)
  • Task (child page)
  • Task (child page)

Single page (combining H1 concept with multiple H2 tasks)

In Experience League, you combine a concept H1 with multiple tasks subheads.

Concept (H1)
Task (Subhead2)
Task (Subhead2)
Task (Subhead2)

Here’s an example of a concept page with task subheadings:

Title: Fallout Report | Adobe Analytics
Description: Learn about Fallout reports in Analytics. Create, run, and share them with Experience Cloud users.

H1 - Fallout report in Analysis Workspace
Para: Conceptual information about Fallout reports and what you can do with them (such as create, run, and share). List prerequisites or caveats, and so on…

H2 - Create a Fallout report
Para: Context about this particular task.
Bold para (orients reader to begin): To create a Fallout report
Steps to create the report.

H2 - Run a Fallout report
Para: Context about this task.
Bold para (orients reader to begin): To run a Fallout report
Steps to run the report.

H2 - Share a Fallout report
Context para about sharing the report
Bold para (orients reader to begin): To share a Fallout report
Steps to share the report.

If you don’t have context information, you can immediately begin the steps after the subhead. The “To” heading should match its parent heading.

• Be brief and generally parallel (in parts of speech) with other entries.

• Avoid adding a product name (unless required for clarity).

• There’s no requirement to exactly replicate the H1 title, but the TOC entry should clearly identify with the H1.

A child TOC entry can rely on the parent as part of the descriptor.

For example: When a parent entry is a feature, and the child entries are directly related, the children can be single-word nouns or verbs. For example:

• Segments

  • Overview
  • Create
  • Share

Example TOC with parallel entries:

The preceding TOC is a good example because:

• Conceptual parent entries are nouns or noun phrases
• Procedures (tasks) are active verbs (not gerunds)
• All entries use sentence capitalization

See Table of contents - editorial guidelines for detailed guidance.

Markdown syntax guidance for TOCs

• A section heading (parent) in the TOC cannot be a link. It has no associated content page. It should contain an anchor such as {#processing-rules}.
• You must use proper syntax for TOC section headings (for example, + Processing rules {#processing-rules}) and TOC article links (for example, + [Article name](article.md)).
• TOC article entries can be a shortened version of the article title if necessary. Follow the standards for writing overviews, concepts, and tasks in this document. See Headings for more.
• Avoid adding the same file multiple times to a TOC (or to multiple TOCs). Doing so causes odd behavior.
• If your repo contains multiple user guides, your user guide directories must be at the same level, such as the subdirectories within the help directory. Each user guide directory must have a TOC file. No nesting user guides. See Multiple User Guides.

See User Guide Setup

Bullets

• Use bullet lists when order is not important.

• Keep list entry brief, usually no more than one sentence (or single word or incomplete sentence).

  Lengthy commentary about the list item should be placed on the next line as an indented paragraph. Your list should be easily scannable.

• Keep all lists grammatically parallel with consistent punctuation style.

• Use periods for complete sentences. If one entry is a complete sentence, all entries should be complete sentences. Don’t use punctuation for single-word entries and incomplete sentences.

Steps

• A step is a single command and must be a complete sentence with a period (or a colon if the step introduces a child list). If your procedure has only one step, use a bullet as the single step.

• A step in a procedure always begins with a verb (or the goal before the action). Example: To run the report, click Run…. If your step has two actions (Click this, then that), combine them into a single, brief sentence. More than three actions in one step becomes confusing.

• After about seven to ten steps, a procedure becomes complex. If you’re creating more than ten steps in one task, consider breaking the task into two, or use sub-steps.

• In product documentation, do not use headings as steps. Headings are different content elements.

  For multi-page tutorials, headings as steps can be allowed. However, do not number them. Rather, spell out Step 1:, Step 2:, and so on.

Step structure and screenshot placement

• If you have information about a step (known as step info), place it under the step (indented on a new line).
• Screenshots should be indented on a new line after the step or action that causes the screen to appear. Info about the image comes after the image, indented, on a new line.
• UI element descriptions can be bullet lists between steps. Keep them parallel.

Example procedure

Here is a sample procedure (Markdown) for signing in at Adobe:

To sign in at Adobe:

1. On `Adobe.com`, click **Experience Cloud**.
1. Click **Sign-in**.
1. Click **Personal Account**.
1. To stay signed in, click **Stay signed-in**.
1. Type your name and password.
1. Click **Sign-in**.

See Steps and lists for a deep dive about writing steps.

When referring to a heading in-line, use a cross-reference link or italics.

When introducing a list of cross-references, use a More help on this topic heading to introduce the list.

• Be parallel in how each list item begins.
• Do not punctuate the cross-reference list items.
• Avoid numbers in headings, which looks out-of-step in cross-reference lists.

Learn how to optimize new and existing documentation and tutorials for SEO.

See Get started with SEO.

• Title metadata is title case and should not exceed 60 characters
• Do not add product names to title.
• Descriptions should be around 150 - 160 characters
• Begin conceptual descriptions with Learn about….
• Begin task descriptions with Learn how to… (tasks) or the verb used in the task.

Detailed requirements

Title and description metadata describe your page for search engines. They are critical for SEO and follow these unique characteristics and requirements:

• They are displayed only in search results as standalone elements, so they need to make sense in that context. (Meaning, they make sense when viewed outside of the page.)
• They serve different purposes from the page name (H1) and first paragraph. (Examples below.)
• Titles should not exceed 60 characters.
• Descriptions should be 150 - 160 characters.
  Descriptions can be shorter, but 160 characters are about the maximum length. The goal is to use as much as the description as possible to target keywords for Google to rank the page higher, while being brief. (Two brief sentences, three at most.)
• Titles use title case (but all other heading and navigation elements are sentence case).
• In Universal Editor, include the pipe and product name.
• Descriptions state what you learn if you read the page. It should include a “call to action,” which is more information about what you learn.
• Playlists home pages should not include the product name (it’s added from solution metadata)

Examples of titles and descriptions

Here’s an example of using a title and page name (H1):

• Title: What is AEM as a Cloud Service?
• Page name: Overview of AEM as a Cloud Service (or, simply, AEM as a Cloud Service)

Here are differences between concept and task title metadata:

• Title for a concept article: Page Views Report (use brief noun phrases for conceptual articles)

• Title for a task article: Create a segment for a Page Views report

For more about titles, see Titles and descriptions.

Description examples

A description is typically one or two brief sentences. The first sentence states what you’ll learn. The second is a call to action or lure.

• For concept articles: Begin with Learn about…

• For task articles: Begin with Learn how to… (or use an active, accurate verb like Create a segment rule using the Segment Manager in Workspace.)

More examples of descriptions

• Learn about segments in Adobe Analytics. Get help on configuring the Segmentation panel in a workspace.
• Find help on using segments in a Page Views report in Adobe Analytics.

SEO examples of using using headings, titles, and descriptions

Here’s an example of relationships between titles, descriptions and corresponding on-page elements:

• Title: What Are Calculated Metrics? | Adobe Analytics

• Description: Learn about calculated metrics in Analytics. Discover ways to create custom metrics and use them, for example, in Analytics segmentation.

• TOC entries: Parent menu: Calculated metrics / Page entry: Overview

• Page name (H1): Overview of calculated metrics

• First paragraph: Calculated and advanced calculated (or derived) metrics are custom metrics that you can create from existing metrics…

Your first paragraph defines the topic and describes what the reader learns from reading the article. Do not use the first paragraph as the description metadata.

Tip: You can use some or all the description metadata as a brief first paragraph. (Learn about… and Learn how to… are useful beginnings.) Be aware that technical requirements (character counts) exist for metadata but not for paragraphs.

Sample conceptual first paragraph

Audiences are collections of visitors (a list of visitor IDs). Adobe’s audience service manages the translation of visitor data into audience segmentation. As such, creating and managing audiences is similar to creating and using segments, with the added ability to share the audience segment to the Experience Cloud.

Sample task first paragraph

Create the customer attribute source (CSV and FIN files) and upload the data. You can activate the data source when you are ready. After the data source is active, share the attribute data to Analytics and Target.

SEO tips for first paragraphs seo-paras

• Include search terms in first paragraphs.
• Use terms that readers use.
• Include synonyms and, if necessary, previous usage of terms. For example, “The Experience Cloud ID Service (ECID), previously known as visitor ID or as acronyms like MID, MCVID, provides a universal, persistent ID that identifies visitors.”
• Include SEO terms in links.
• Avoid placing essential terms in complex tables. Complex tables don’t yield reliable search results. Text in images is not search. Captions are searched.

Title metadata

Title metadata should be title case (as an industry standard for SEO, scanning, and readability).

Example of how title metadata displays on Google:

Product names and proper nouns

Adobe, Adobe Analytics, Experience Manager, and so on.

Do not capitalize for stylistic reasons or because a word seems important.

Feature tags

Feature tags (see the feature YAML) are title case (and case-sensitive for validation).

Feature names

Match the capitalization that you see in the product interface when referring to a feature.

Interface elements

Match the capitalization shown in the product interface.

Colons and lists

Capitalize the first word after a colon and the first word of each bullet in a list.

Quotation marks: Quotes are intended only for quoting people, which is rare in software documentation.

• Do not apply quotes to interface elements. Use UICONTROL (and bold in navigation and steps).
• Do not apply quotes when italics accomplishes the same goal.

Italics: For emphasis. Use italics for error messages, referenced headings (that aren’t links), strong emphasis, and uncommon (or foreign) words that are potentially confusing.

Bold: Bold on UI elements helps readers navigate. Use bold with UICONTROL for elements (especially actionable elements in steps). (Bold helps improves content scanning). Use bold on a paragraph to create a false heading (in FAQs). Do not use bold for emphasis.

Punctuation in headings: Do not include punctuation in headings except in rare occasions to ensure clarity, such as a colon in the name of a parameter.

• A what’s new heading should read as a statement, not a question.
• Questions in FAQs should use question marks, but these questions should be bold paragraphs, not headings.

The Adobe writing guide covers general grammar and usage guidelines for all Adobe. The Microsoft® Manual of Style is also an industry-accepted authoring style guidance.

Improve your clarity (and Acrolinx scores)

Here are simple ways to improve content design, clarity, and readability. These also help improve Acrolinx style scores and CQI scores on ExL.

For the VSC extension, use https://adobe-api.acrolinx.cloud/ as the server.

Acrolinx is similar to a grammar and spelling checker you use in Word. However, it’s much more powerful.

Acrolinx:

• Enables findable, scannable, and easy to read content
• Corrects spelling and grammar
• Helps with consistency with Adobe brands and terms
• Optimizes content for localization

See Acrolinx to set up the VSC extension and find find baseline reports.

The rule of thumb is to shoot a screen for the specific feature (rather than a whole page), and to include some surrounding UI context for recognition.

Strike a balance between including details that provide context to the screenshot and adding too many distracting elements.

Consider downloading Snagit (using Adobe’s discount) for screen captures. (Get manager approval.) It can also be a tool for video tutorials.

Use Light theme (not the Dark theme) in the Experience Cloud UI preferences.

For detailed guidance, see Screenshots.

Add meaningful alt-text to your assets (images). Consider alt-text that matches:

• The goal customers can accomplish (task or concept name)
• The feature or page you’re showing
• The icon name that you’re showing

Google considers the alt-text in SEO results.

Usage note: A file name is the name of a file. Filename refers to a programming task.

File names must be SEO friendly and readable.

For example, calculated-metric-overview.md is better than calc-over-01.md and single-words like overview.md or introduction.md.

Guidance:

• Guide-level tutorial home pages are overview.md.

• Guide-level documentation home pages are home.md.

• For feature overviews use topic-overview.

• For action (task) files, like create, use action-topic. (For example:create-calculated-metric.md)

• Always uses dashes, no underscores in filenames. Both for articles and images or other files.

• Never capitalize any character in a filename.

• Avoid numbers in file names

When instructing readers to type user-configured or user-created values, use inline code syntax. Code preserves English and is intended for:

• File names
• URLs
• Folders
• User-defined, input terms (under evaluation)
• Code (and code blocks)

(Under evaluation with localization)

Use bold for keyboard actions.

cmd + shift + p

Here are common words used in procedures, and what they mean:

• Open: Use for applications and programs. “Open the Segments panel.”

• Close: Use for applications and programs. “Close the Dimensions window.”

• Leave: Websites and pages. “Leave Report Builder.”

• Go to: You go to a tab or place in the UI. “From the File menu, click…” “Go to the File menu…” “On the Reports tab” (Go to a tab or place in the UI)

• Select: Select is about marking text, cells, and similar items that are subject to a user action (such as copying text), and also about picking options from a list.

• Click: Click is about mouse actions. “Click Find.” Note the following best practices for click

• Dropdown: Use dropdown menu (not dropdown list or dropdown listbox).

• File name: Two words. Filename is a programming term.

Avoid calling out control types (i.e. “Click the Enable radio control…”) unless knowing the control type is important for clarity (like the File menu). (Control type names might not localize well or can change during development.)

More resources:

• Adobe’s In product word list in Spectrum for guidance.
• Adobe’s Writing Guide for all writing and grammar questions not documented here.

Product names are in breadcrumbs and added to title metadata automatically.

• Do not add a product name to headings and TOC entries unless leaving it out causes confusion.

• Do not add product names to title metadata.

• Do not add the (the article) before a product or feature name (unless it’s part of the name).

  • Correct: Get started with AI Assistant. Learn about audiences in Experience Cloud.
  • Incorrect: Get started with the AI Assistant. Learn about audiences in the Experience CLoud.

• Follow corporate guidance for first and secondary mentions. (Adobe is not needed in secondary mentions.)

  For corporate identity, we usually include Adobe in the first reference of a product at the guide level. Depending on space considerations, you can drop Adobe in a heading, but then the first reference in the body copy should include the full name. Certain products, such as Adobe Audition and Adobe Premiere Pro, require the use of Adobe on first or most prominent reference in every piece of collateral because it is part of the legal, trademarked name.

• Use acronyms sparingly (okay for SEO or to shorten a heading that requires a product name).

• Understand DNL (and UICONTROL) Markdown tagging for localization.

To locate Adobe’s brand guidance:

1. Go to Brand Guidelines and FAQ https://inside.corp.adobe.com/brand-center/guidelines.html on Inside Adobe.

2. Locate the appropriate brand guidelines and download its PDF document for reference.

For rebrands on ExL, use the official product name list (internal wiki, tracks rebrands) and reach out to Blake Frei.

When wrapping product names or interface terms in localization tags, use explicitly the terms shown in the UI. (Do not add punctuation, apostrophes, quotes, and so on.)

When referring to hard-coded UI elements, apply UICONTROL with bold. This is required in steps, recommended for clarity in paragraphs.

Example:

1. Click **File** > **Print**. **Element name**

• For file names, code, URLs, directory names, error messages, and so on, use code (back ticks)

More guidance:

• For DNL and UICONTROL guidance, see Apply DNL and UICONTROL to interface strings.
• For general localizing SCCM (Markdown/GitHub) information, see Localization.

To submit a Universal Editor page (such as Perspectives content) to localization, see How to submit items for Translations for instructions. (Wiki)