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:

Tips for improving your writing clarity

Here are authoring tips for improving clarity, readability, and improving Acrolinx style scores:

Item Usage
Use active voice Change passive voice to active voice
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.
Use present tense Incorrect: Control types will change over time.
Correct: Control types change over time.
Add nouns after pronouns This, that, these, those, and it.
Alone, these pronouns are confusing. Use nouns after pronouns.
Example: This feature enables…
Avoid weak adverbs Very, extremely, incredibly
Adverbs are extra words that do not add significant meaning when you use strong and exact verbs, clauses, and adjectives.
Add text between headings You should not have two headings in a row without text between them.
Create clear procedures A step is a brief, numbered, single-sentence command with these guidelines:
  • If you have commentary or information about a step, place it below the step (indented) or below the asset (screen shot, video, or interface description) following the step.
  • If your step has two actions (select this, then that), write it as a single sentence.
  • If a step has a specific goal, mention the goal before the action. Example: To stay signed in, select Stay Signed In.
  • Begin the step with a verb (see exception above).
Example steps:
  1. On Adobe.com, select Experience Cloud.
  2. Select Sign-in.
  3. Select Personal Account.
  4. To stay signed in, select Stay signed-in.
  5. Type your name and password.
  6. Select Sign-in.
Note the verbs used and where they are placed in the steps.
Avoid quotation marks Quotes indicate dialogue. Situations for using quotes in product documentation are extremely rare. To set off a word or phrase, consider italics. For interface names, use bold and/or UICONTROL. When bold isn’t needed, use italics.
Follow these guidelines
  • 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.
  • Colons: Use colons to introduce a list. Use colons sparingly within sentences. Capitalize the first word after a colon in a sentence.
  • Keep lists parallel.
  • Avoid gerund (ing) verbs for headings.
  • Use sentence style caps for headings.
  • Capitalize formal names (not important words).
  • Use the Oxford comma (three commas in a list).
  • Keep sentence length under 39 words.
  • Navigation: use go to or navigate to.
  • Avoid raw URL text (use user-friendly link text) unless the path is important information.
Use a spell checker in VSC Install Code Spell Check (extension) in Visual Studio Code.
Change click to go to or select Click is a device-specific word (with accessibility issues), and the trend is to move away from it. Here are suggestions for changing it:
  • Navigation: Go to File > Print.
  • Clicking: Select File > Print or Select OK.
See Describing interactions with the UI for more ideas on the best word choice in various situations.

A few more best practices in technical writing:

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

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

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.

Capitalization

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

Table of contents

The ‘TOC.md’ 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](article.md)).
  • 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 current.md. https://git.corp.adobe.com/AdobeDocs/release-notes.en/edit/review/current.md

  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