DocumentationExperience League Authoring Guide

Editorial guidance for Experience League authors

Last update: Fri Mar 27 2026 00:00:00 GMT+0000 (Coordinated Universal Time)

This page provides simple editorial guidance for authors documenting Adobe enterprise products and features. Specifically, it applies to the Markdown repositories sourced in GitHub Enterprise or AdobeDocs.

Infrequent authors: This page is also topically relevant to infrequent authors using Universal Editor (browse pages, Perspectives, and courses). For an overview of publishing formats and contacts, see Experience League Content Authoring Hub (internal document).

Writing and structure basics

SEO and metadata requirements

Steps and lists

Writing and editorial guidance

Concepts and tasks content-types

Before beginning, understand your main goal. Is your page intended to:

  • Describe a product or feature conceptually?
  • Walk though a task

content type. Is it a concept, task, or a combination of both?

  • Concepts: Introductions, overviews, and any information explaining what a customer can do with the product or feature.

  • Tasks: Information about how to use the product or feature.

Knowing the page-level content type affects how you author headings and metadata, and arrange elements your page. Content elements can be a heading, paragraph, prerequisite, step, information about a step, list, screenshots, subheading and so on.

What is a concept?

A concept is about the what and the why you use a product or feature. Examples of concepts are introductions, overviews, and brief conceptual information preceding a task (steps).

Keep concepts separated from tasks. 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:

  • Overview of segmentation
  • Processing options in Analytics
  • Campaign integrations
  • Audience services

Do not place the following types of content in a concept content type (such as an overview):

  • Screenshots (unless you are generally showcasing the UI)
  • Steps (place how-to content under a task heading)
  • Navigation (reserved for steps)
  • Interface element descriptions

What is a task?

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

  • 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.

To learn about arranging concepts and tasks on a page, see Structure tips.

Headings headings

At-a-glance guidance:

  • Use imperative verb headings (for tasks) (avoid gerunds).
  • Use nouns and noun phrase headings for concepts.
  • Use sentence case for all headings (proper nouns excepted).
  • Do not punctuate headings (question marks allowed if the heading is a question). If your heading has a comma, it’s likely too long.
  • Be descriptive but brief, such as Create a targeting workflow
  • Do not stack headings. At least one sentence must exist between headings.
  • Avoid mentioning product names in headings unless needed for clarity.
  • H1 and its TOC entry should either match or closely relate. Single-word verbs are okay for TOC entries.
  • Do not place badges in headings. Include only words.
  • Anchored headings should not be numbered steps. (More guidance and exceptions below.)

First paragraphs paras

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.

Subheadings subheadings

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

Structure tips for concepts and tasks structure

Common structural examples for concepts and tasks.

Concept parent with child task pages (multipage example)

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)

Table of contents toc

  • 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:

Parallel TOC

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

SEO guidance seo

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

See Get started with SEO.

Title metadata requirements title-metadata

  • Title metadata must be title case.
  • Title metadata should not exceed 60 characters.
  • Do not add product names to title. (The pipe and product name are added automatically)
  • Titles serve different purposes from the page name (H1) (examples below.)
  • Playlists home pages should not include the product name (it’s added from solution metadata)
  • In Universal Editor, you can add the pipe and product name manually.

Description metadata requirements description-metadata

Descriptions are a brief summary that explains the content’s purpose, scope, or key details. The first sentence helps users and systems understand what a is about. The second sentence should be a “call to action,” helping users know what they can accomplish.

  • Descriptions are one or two concise sentences.

  • Descriptions should be around 150 - 160 characters

    Descriptions can be shorter than 150 characters. However, 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.)

  • Begin conceptual description metadata with Learn about… or a concept-related verb like Understand ways to…, Get help on…, and so on.

  • Begin task description metadata with either Learn how to… or an imperative verb used in the task (create, set up, implement, and so on).

Examples of titles and descriptions

Title examples

How a title and page name (H1) can differ or relate:

  • Title: What Is AEM as a Cloud Service?
  • Page name: Overview of AEM as a Cloud Service

Concept vs. task title metadata:

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

  • Title for a task article: Create a Segment for a Page Views Report

For info about how ExL uses titles, see Titles and descriptions.

Description examples

  • 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 headings, titles, and descriptions

Here’s an example showing the relationship between titles, descriptions and corresponding on-page elements for a Calculated Metrics page:

  • 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…

Description for a home (landing) page

Here’s a standard description for a home page that you can use:

Search for self-help articles and tutorials on Adobe (your product name). Learn strategies and best practices from experts in live and on-demand video events.

Metadata requirements metadata

Metadata improves content quality and enables search engines and AI to find information. On Experience League, metadata helps readers filter search results by product, role, and content type (and more).

Key things to know:

  • Values in the metadata.md apply to an entire repo (such as solution)
  • Values in the TOC.md apply to a guide (such as role)
  • Values in the article (such as feature) apply to the article
  • Article (page) values supersede TOC.md and metadata.md values
  • TOC.md values supersede metadata.md (repo) values
Learn more

Example metadata

Example of metadata

Certain metadata values display on published pages. For example, when you add feature, role, and level tags, their values display in the TOPIC and CREATED FOR areas on Experience League.

Example of metadata

See the Metadata and tag reference page for more information about each value.

Steps and bullet lists steps

Bullets

  • Use bullet lists when order is not important.

  • Keep each 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.

More help on steps

Cross-references references

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.

Cross reference 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.

Capitalization capitalization

All navigation elements, headings, and subheadings use sentence case. This standard follows general Adobe guidance in the Adobe Style Guide.

There should be few exceptions to the sentence-case guideline. If initial caps are used, all words are capitalized except articles and prepositions or conjunctions of four letters or fewer.

Exceptions:

  • Title metadata. Title case is required for title metadata.
  • Feature metadata (case sensitive, follows feature YAML values)
  • For proper nouns (product names, capitalized UI elements and features)

Punctuation and emphasis punctuation

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.

Dashes (em and en):

  • Use en dashes to hyphenate words as appropriate for grammatical clarity.
  • Avoid em dashes. They are intended for creative (or marketing) writing but can introduce confusion for translators and authoring tools.

Colons:

  • Colons are more appropriate in software documentation than em dashes.
  • Use them to introduce a list (bulleted or commas in a sentence).
  • Capitalize the word after the colon only if the colon introduces a compete sentence (or the word is a proper noun).

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.

Clarity and writing style style

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.

Guidance
About
Use active voice
Change passive voice to active voice
Use present tense

Less clear: Campaign v8 will release in June.

More clear: Campaign v8 releases in June.

Present tense is always easier to read for customers.

Avoid weak, needless adverbs

Very, extremely, incredibly…

Adverbs are extra words that do not add significant meaning if you use strong and precise verbs, clauses, and adjectives.

Use strong verbs for titles and TOC entries

Examples:

Weak: Trait creation and management

Strong: Create and manage traits

For more heading and title guidance on word choice, see Heading names and page titles.

Capitalization
See Capitalization on this page for guidance.
Learn these small tips for clarity
  • Avoid In order to (it adds no meaning). All you need is to.
  • Avoid Utilize. It might sound more technical, but it isn’t. Utilize means to make good use of, especially of something that was not intended for the purpose but will serve.
  • Avoid semi-colons: Use a period instead and begin a new sentence. Semi colons introduce needless complexity.
  • Colons: Use colons to introduce a list. Use colons sparingly within sentences. Capitalize the first word after a colon in a sentence.
  • Use the Oxford comma (three commas in a list).
  • Keep sentence length under 35 words.
  • Navigation: use go to or navigate to.
  • Avoid raw URL text (use user-friendly link text) unless displaying the path is important information.
Use a spell checker in VSC
Install Code Spell Check (extension) in Visual Studio Code.
Run Acrolinx in VSC
Acrolinx checks for style and grammar issues. It checks URLs, terminology, spelling, and more. It helps you improve your clarity and improves translation on Experience League content.

Screenshots and images assets

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.

Alt-text alt-text

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.

Alt-text should follow general Adobe authoring guidelines. You’ll find excellent ideas and guidance in Adobe Spectrum. See Writing with visuals.

File names filenames

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

User input elements input

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)

Keyboard actions keyboard

Use bold for keyboard actions.

cmd + shift + p

Words and terms words

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:

Branding, product names and icons brands

Learn about using product names, first and second mentions, application icons, and find branding guidance.

Application icons: Do not use application icons to identify apps or features. If icons appear in screen captures and videos, that’s acceptable.

Product logos: Adobe recommends using product lockup style logos available in the Marketing Hub.

Product names:

  • In title metadata: Do not add product names to title metadata. Product names are added automatically.

  • In description metadata: Use product names strategically as a keyword for SEO.

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

  • With articles (the): Do not add the (the article) before a product or feature name (unless the article is 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.

  • First and second mentions: 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.

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

  • Acronyms: Use acronyms strategically for SEO or to shorten a heading that requires a product name.

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

NOTE
Adobe recommends not sharing the brand guidelines PDFs directly. The guidelines have limited usage rights and everyone must access it via the portal, after accepting the terms and conditions.

AdobeDocs Chrome extension adobedocs

Add the AdobeDocs Chrome extension to see the metadata on an Experience League page.

Do not localize tag dnl-tag

Learn about DNL for localization

UICONTROL tag uicontrol-tag

  • Apply UICONTROL to interface features and labels in markdown.

  • Do not add punctuation, apostrophes, quotes, and so on. Use the exact labels and characters shown in the product interface.

  • When referring to UI elements in steps (procedures), apply bold around the UICONTROL term.

Example:

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

More guidance:

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

Code tag code-tag

For file names, code, URLs, directory names, error messages, and so on, use code (back ticks). This tag preserves English and applies the code font.

recommendation-more-help
92f1a422-8a81-400b-85d3-388f0c36dfda