Authoring style guide and SEO for Experience Cloud writers

This page is for content authors publishing to Adobe Experience League. It provides authoring standards, guidelines for SEO, tips on information design, and explanations about content types. Markdown tips follow the authoring standard sections.

Additional information about content authoring that is not covered here can be found at the following locations:

New writer onboarding

Visit the New Project Publication Checklist page to get started. If you’re have never authored in Experience League, or you want to migrate from another source (like Helpx), there is important planning you need to do.

Where to find tools and useful information as a new writer:

Item Information
Adobe Doc Github Repo You’ll need a github account to access this repo.
Visual studio code The recommended Markdown authoring tool
Jenkins The publication and activation pipeline.
Help landing page All of the help guides for Experience Cloud
Docshare \\\share\dxdocshare The old Tools directory for (DITA/XMetaL writing team) You can find legacy tools, SnagIt, XMetaL, and archived Frame guides. You’ll need to map to this location. If you need rights, contact Blake Frei.
Authoring guide The published version of this guide.
Release notes published The production URL for release notes (and Early Access version)
Release notes staged (not yet available) The staging URL for Internal Review release notes.
Release notes repo Release notes git repo.
Release notes wiki Authoring instructions for release notes. (Contact Blake Frei with questions)
Marketing Docs team wiki The old team wiki for the DITA/XMetaL writers.

Branding guidelines for Experience Cloud

For information about product names and branding guidelines, follow these steps:

  • Access Adobe Marketing Hub and log in.
  • Click search icon and search for the required brand guidelines, for example, search for ‘Experience Cloud guidelines’ term.
  • Locate the appropriate brand guidelines and download its PDF document for reference.

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

First paragraphs

Your first paragraph should define the topic and describe what the reader learns from reading the article.

Sample first paragraph (concept):

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 first paragraph (task):

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

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


  • Adobe style uses sentence-style capitalization for all headings.
  • All words are lowercase except the first word and proper nouns, such as the names of brands, solutions, and services.

Technical writing tips

A few best practices in technical writing:

  • Voice: Use active not passive voice. Active voice is considered more concise, direct, easier for readers to understand.

  • Tense: Avoid the future tense. Describe what occurs after an action, not what will occur.

  • Sentence length: Use big ideas with fewer words. Translation is more difficult as sentences grow in length and complexity.

  • Procedures: See Tasks above. A step is one sentence. Place information about the step on a separate line.

  • Lists: Make your lists parallel. For example, each item should be a noun or a phrase that starts with a verb.

  • Scannable content: Help readers find what they need quickly, or recognize just as quickly when they’re not where they need to be. Writing to facilitate scanning will help.

  • Numbers: In body text, spell out whole numbers from zero to nine, and use numerals for 10 or greater. See Numbers.

  • Avoid the following words, phrases, punctuation, and styles:

    • In order to: This phrase is a wordy substitute for to.
    • Will: Th future tense should rarely appear in technical writing.
    • Utilize: It might sound more technical, but it isn’t. Utilize has a special meaning: to make good use of, especially of something that was not intended for the purpose but will serve.
    • Semi-colons: Use a period instead and begin a new sentence.
    • Commas: In a list of three or more items, include the last comma (a comma before the conjunction). (KNown as the Oxford or serial comma).
    • Colons: Use colons to introduce a list. Use colons sparingly within sentences. Capitalize the first word after a colon in a sentence.
    • Quotations: These indicate something is spoken. In most cases, use italics instead of quotes. See Punctuation in the MSFT Manual of Style.
  • Capitalization: When in doubt, don’t capitalize. In headings, use sentence-style capitalization. Capitalize proper nouns and the first word after a colon. See Capitalization.

  • Write like you speak, project friendliness, and get to the point fast.

See Top 10 Writing Tips in the Microsoft Style Guide for more information.

Table of contents

The ‘’ is your table of contents. Each guide should have one.

  • A section heading (parent) in the TOC cannot be a link; it does not have a page with content. It should contain an anchor such as {#processing-rules}.
  • You must use proper syntax for TOC section headings (e.g., + Processing rules {#processing-rules}) and TOC article links (e.g., + [Article name](
  • TOC article entries can be a shortened version of the article title. Follow the standards for writing overviews, concepts, and tasks in this document.
  • 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

Bold and italics

  • Use bold text only for interface elements you click in a procedure (and with UICONTROL).
  • Use italics for emphasis or when a word is confusing without it. For example, a foreign word, or when you’re describing a word or defining a term.

See Markdown Syntax Style Guide for more information.

Spelling and punctuation

Adobe documentation uses standard American English spelling and punctuation:

Use American English spellings for words like “color,” “recognize,” “meter,” and so on.

Place closing quotation marks outside a comma and period. For other closing punctuation, placement of quotations marks depends on whether the punctuation is part of the text being quoted. Examples:

  • What is a “profile”? (Preferably, use italics in this situation. What is a profile?)
  • “Hello, world,” she said.
  • The page displays the error message, “Message has unknown format.”
  • “Is anybody out there?” she asked.
  • A type of trojan is called a “trojan clicker.”

When writing code samples, always follow the conventions of the coding language being used (such as JSON, JavaScript, Python, etc.). Example:

/*Declare the string to have length of "constant+1".*/

Word choice

Avoid referring to your audience or Adobe product users as “customers.” Doing so implies that we see them only as sources of money. You can, however, refer to the user’s customers:

  • Don’t: “A customer may only process 175 batch segmentation jobs per year.”
  • Do: “You may process up to 175 batch segmentation jobs per year.”
  • Do: “Experience Platform enables your organization to see a 360-degree profile of each of your individual customers.”

Use positive phrasing:

  • Don’t: “You can process only 175 batch segmentation jobs per year.”
  • Do: “You can process up to 175 batch segmentation jobs per year.”

Release notes authoring

  1. In the review branch (previously called ‘staging’), edit

  2. Commit and push to the review branch directly. (No need for a pull request when working in the review branch.)

    Review is used for the internal review. After Early Access is published (goes to production), you can make updates in Master. Create a PR and communicate with Blake for publishing.

Publish to production (activate in Jenkins)

This procedure assumes that you have previously published your guide:

  1. Ensure that your repo validated successfully in Jenkins (you’ll receive a failure email if the repo did not validate).
  2. In Jenkins, sign in, click activate, then click Build with Parameters.
  3. Type the repo name (without the language code, such as release-notes).
  4. Type the language code (typically en).
  5. Specify the Instance (typically Production).

See Activate content

Locate a validation error

Writers, documenting every validation error requires your help. Feel free to add to this section when you find new and useful tips on fixing issues. More help is available in Resolve Validation Errors.

Locate a validation error

  1. In Jenkins find your repo (guide) name under Production or PR (pull request), then click your repo name.
  2. Click the latest build number.
  3. Click Console Output.
  4. Under Summary, look for Fail.
  5. Click Show Details for the failure category (such as Link Checker, or DITA to HTML)

Locate a DITA validation error

  1. Go to Build page > Build Artifacts > out/dita/help/using/….
  2. Locate the file referenced in the DITA to HTML error.
  3. Open the file (in VS Code or Notepad++).
  4. find the line number referenced in the error. See DITA errors for more information.

Common validation problems and tips to prevent errors

Problem Solution
Backslash characters \ in internal cross-references. These break DITA generation. Use forward slash characters /
<> - Angle brackets break validation (DITA) Escape them in Markdown. See Characters to Escape.
Extra spaces No space between the markers of the text or surrounding the links. Examples: abcd or [ abcd ]
TOC doesn’t update after publishing Enable Rebuild when publishing content in Jenkins > Activate > Build with Parameters.
TOC fails to validate (section IDs) Every section heading must have a valid section ID. Example: Processing rules {#processing-rules}
TOC section heading fails Section headings cannot be links.
Filename fails to validate Markdown filenames must be lowercase with hyphens. No capital letters, underscores, periods, or spaces.
Blank lines Headings, fenced code blocks, and lists should be surrounded by blank lines.
Headings - hierarchy One H1 (#) per document (the page title). The first line below metadata is the H1. No leapfrogging heading levels.
Headings - punctuation No periods allowed in headings (use hyphens).
Headings - numbers Do not start a heading with a number (localizing a date can cause a heading to begin with a number). If you need a release date in the heading, add Release Date before the actual date. Ditto fore version numbers in headings.
Heading IDs (anchors) No duplicate heading IDs (anchor IDs) are allowed in a document.
404s When you rename files or move files to a different location in the TOC, you change URLs and create 404s.
Hidden characters Careful with copy and pasting from other sources. Copying from PPT brings in odd characters (like vertical tab character). Notepad++ doesn’t strip out hidden characters or expose them. Note: pasting them into an editor like BB edit exposes hidden characters. Changing characters from UTF8 exposes hidden characters.

VS Code

Information about extensions, shortcuts, and tips when authoring in VS Code.

Additional resources

For general information not mentioned here about content authoring, best practices, and terminology, consult the Markdown Style Guide. See Markdown Syntax Guide to learn how to author in Markdown.

On this page