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:

• Improving Search Results
• Adobe CHL style quick-reference
• Adobe editorial guidelines at WCM
• Microsoft Manual of Style

New writer onboarding

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 \\sjshare.corp.adobe.com\share\dxdocshare	The old Tools directory for marketing.adobe.com (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 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.

Headings and page titles

Follow these guidelines for headings:

Guidelines	Examples
Use sentence-style capitalization	Headings should use sentence style caps (per Adobe’s standards). Example: Create a workspace
Keep headings short	Keep page titles short with important words at the beginning.
Use nouns and short noun phrases for headings (and TOC entries)	Audiences or Experience Cloud integrations
Use keywords	Keywords improve search results. Create meaningful headings in an active, natural language.
Use infinitive verbs for task headings	Run a Fallout report
Use the singular form for task headings	Save a workspace
Use sentence style capitalization for all headings	Create an audience
Use parallel structures	A table of contents (TOC) or list should begin with the same verb or noun phrase. (see Structure and syntax for headings)
Avoid double headings	Avoid following a heading with another heading. At least one line of text must separate headings.

Structure and syntax for headings

Information design typically follows an overview > concept > task hierarchy. In highly structured authoring environments (like DITA), these content types are defined as separate pages or files, which are merged at help-build time. In Markdown authoring, you can put these content types natively on the page.

Overview
  Concept
    Task
    Task

For example:

  Reports
    Fallout report
      Run a Fallout report
      Print a Fallout report
  Dimensions
    Dimension types
      Add a dimension to a table
      Create a calculated metric using a dimension
      Field descriptions

Markdown heading syntax

More on headings from CHL…

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.

Concepts and overviews

Concepts precede a task. They provide background or overview information that users must know before they can successfully work with a product or interface. Often, a concept is an extended definition of a major abstraction such as a process or function. It might also have an example or a graphic, but generally the structure of a concept is fairly simple.

Overviews provide conceptual background information that users must know before they can successfully work with a product or interface. Write an overview for:

• Solution or product
• Large features that contain (but don’t necessarily require) multiple procedures

See Authoring standards for headings above for authoring standards.

Sections

A section represents an organizational division in a topic. Sections are used to organize subsets of information that are directly related to the topic. Multiple sections within a single topic do not represent a hierarchy, but rather peer divisions of that topic.

The following structure shows a sample concept with child sections:

Fallout reports
 Types of Fallout reports
 How to interpret Fallout reports
 Fallout reports in Report Builder
 Fallout reports in Analysis Workspace

Tasks (procedure)

A Task answers “How do I?” questions. They have a well-defined structure that describes how to complete a procedure to accomplish a specific goal.

For an article with subtasks, use a noun phrase for the article title, then imperative verbs for child tasks. Examples:

Symbols
 Create a symbol
 Modify a symbol
 Redefine a symbol

What’s in a task

Limit task information to:

• Navigation
• Screens
• Interface elements to click or complete to accomplish the task
• Field/option descriptions

Authoring standards for a task

• Use sentence style capitalization for a task heading.
• Add conceptual information (including prerequisites), where necessary, before the steps. (Most conceptual information should reside in the overview preceding the task, but some tasks require contextual conceptual information.) If you find yourself adding more than a paragraph of conceptual information before the steps in a task, you likely need to create a concept heading.
• Steps: Use Markdown syntax. A step is a command that contains only one brief command: the step users take. Extra information (step results, images, information about the step) must go on the next line.
• Images: Store graphics (screenshots, process graphics) in the Assets folder in the guide, and link to the asset (using Markdown syntax).

Fields and options

Document the navigation to (and definitions for) interface fields and options in Task (steps) content types. If you find yourself doing this in a concept, overview, FAQ, or anywhere outside of the procedure, the information is in the wrong place. Additionally, use bold UICONTROL for interface elements so that readers can scan for this information. When they find the bold UI element name, everything they need to know about the UI element should be in the definition or close to it (in the step).

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.

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 ‘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 staging branch, edit current.md. (https://git.corp.adobe.com/AdobeDocs/release-notes.en/edit/staging/current.md)

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

   Staging 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

Publish to stage

You can stage content that you do not want to publish. Publishing to stage enables internal reviewers to review formatted content without the requirement to log in.

1. If you have a new guide, contact SSE to help set up the repo for validation.
2. In Git Desktop, create a new branch called staging.
   When you commit to the staging branch, content is published to: docs-author-stg.corp.adobe.com.
3. In Jenkins, click activate, then click Build with Parameters.
4. Type the repo name (without the language code, such as release-notes).
5. Type the language code (typically en).
6. Specify the Instance (Stage).

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.

• Common validation errors (wiki)
• Validation troubleshooting
• Validation video

VS Code

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

• Microsoft Visual Studio Code Tips (wiki)
• VS Code tips and extensions

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.