Editorial guidelines for Experience League writers

This page is a quick reference for content authors publishing to Adobe Experience League. It provides quick links to your primary resources for content quality, best practices of information design, and a round-up of ExL authoring standards.

Frequently accessed links for content authors (Linkcheck, Acrolinx, dashboards, and so on):

  • Link check (ProjectLinkCheck in Jenkins) - Go there often to see if you have broken links.
  • Acrolinx - Learn about and install the extension. View your baseline reports from Acrolinx and see the issues that lower your scores.
  • CQI Power BI Dashboard - Create a workspace to consolidate and organize CQI (content quality index) inputs from various sources. View exactly how your repo is doing in every category.
  • Metadata help - Learn how ExL uses metadata and how to add it to your pages.
  • Video quickstart - Learn how to record, edit, add videos to ExL, and so on.
  • Authoring Guide Home - All topics are listed on that page. Do a local Find to search for information.
  • Docs GitHub - Our corporate Adobe Docs GitHub.
  • Marketecture slides - See product names and how the product is described by Marketing.

Best practices of technical writing

Software documentation is highly specialized. Even the most prolific novelist gets flustered when attempting technical writing–not because the material is complex or technical, but because it’s not easy making complex, technical information simple.

Learn the tricks of the trade and the common pitfalls to avoid so that your content is structurally consistent, scannable, reusable, and flows through the publishing pipeline.

Here are common issues to watch out for:

Headings not separated by text (double headings)

If you have two headings with no text separating them, add missing text (to introduce the second topic heading). Or, you can remove one of the headings. The second one is probably unnecessary.

For example, Overview serves no purpose here:

Double headings

  • Also, if your second heading happens to be Overview, it’s probably unnecessary. Your H1 and first paragraph serve as the conceptual overview about the article’s topic.

  • Similarly, for SEO purposes, stand-alone headings like Overview and Introduction aren’t useful. Name the product or feature that you’re introducing. (Example: Overview of Fallout reports)

    See Headings for more information.

Inconsistent cross-reference headings

Use More information headings for cross-reference lists (or maps). Example:

Cross reference list

Guidance for cross-reference lists

  • Use a bullet list for the cross-references

  • Use italics for the formal names of guides or page names (when not using link text)

  • Do not punctuate the heading (or any heading)

  • Avoid numbers in headings

    See Headings for more information.

Mismatching TOC entry, breadcrumb, and page name

Because we manually manage the TOC (table of contents) file, these mismatches are easy mistakes. Ensure that your TOC entry matches your page name (H1). Also, ensure that it closely matches the breadcrumb.

Guidance on TOCs and lists

  • You might need to shorten your TOC entry, but it must clearly relate to the page name and breadcrumb.
  • Breadcrumbs are pulled in from the title metadata, so they can differ (for SEO purposes).

See TOC on this page for more guidance.

Quotation marks instead of italics

It’s hard to resist adding quotes around a word or phrase. However, quotes are intended for quoting people, and almost never used in product documentation.

Guidance on quotation marks

  • Usually, italics work better than quotation marks (for error messages, unique or foreign words, and so on).
  • For interface elements, use bold and UICONTROL.

Procedures

Writing a procedure (the task content type) is not a talent that we are born with. Building a readable, clear procedure takes practice.

Guidance for steps

  • A procedure is a series of steps. A step is a brief, numbered, single-sentence command.
  • Begin each step either with a verb or the To infinitive (to orient the reader to the goal, as in, To stay signed in, enable ABC)
  • If a step has a specific goal within the overall procedure, mention the goal before the action.
  • If you have information about the step (a content type called step info, add it after the step (indented with the step) or after the asset (a screenshot, video, or a list of interface descriptions).
  • If your step has two actions (such as, Select this, then that), write it as a single, brief sentence.
  • Limit your procedure (task) to about seven to ten steps. If you’re creating more than ten steps in one task, you likely need to break it into two tasks. Use your best judgment here.
  • In product documentation, do not use headings as steps. (Exception below.)
  • 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.

Example procedure

Here is a well-structured procedure for signing in at Adobe:

To sign in at Adobe:

  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.

Parallel lists

Using parallel construction for lists makes reading and scanning easy. Lists include a TOC, bullet lists, or numbered lists.

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

Title and description metadata

These metadata are important for SEO, content discovery, and content quality scores on Experience League.

Here are examples of titles and descriptions:

Descriptions for concept articles

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

Descriptions for procedure/task articles

  • Learn how to create a segment in Adobe Analytics.
  • Create a segment in Adobe Analytics. Learn how to select, configure, and run a report based on the segment you create.

The one you use depends on the size and scope of the article.

Title for a concept article

  • Segments in Page Views reports

Title for a procedure/task article

  • Create a segment for a Page Views report

(Remember, the pipe and product name are added automatically to titles.)

See Titles and descriptions to learn more about these metadata.

Ways to improve 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 Weak: Campaign v8 will release in June.

Strong: 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.

Use sentence capitalization When in doubt, don’t capitalize. In headings, use sentence-style capitalization. Capitalize proper nouns and the first word after a colon. In procedures, match capitalization that you see in the interface.
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 39 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.
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.
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.

A few more best practices and resources:

  • Usage guidelines wiki - A great internal wiki that provides usage advice from A to Z. (Hat tip: Scott Rhoades, Experience Platform)
  • 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 can help.
  • Numbers: In body text, spell out whole numbers from zero to nine, and use numerals for 10 or greater. See Numbers.
  • 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.

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.

Localization - DNL and UICONTROL

You do not need to worry about whether your product is localized or the languages that ExL uses. However, you help improve the quality of localization by applying the following two (required) Markdown tags where appropriate:

  • DNL

    DNL means do not localize. You use it only for trademarked Adobe product names, all of which must remain in English.

    Syntax examples: [!DNL Adobe Campaign] or [!DNL Workfront]

    DNL is not intended for file names or URLs.

  • UICONTROL

    UICONTROL indicates an interface control (such as an option, field, tab, page, group of options, or feature name in the UI).

    Syntax example: Select **[!UICONTROL Project]**, then select **[!UICONTROL Save]**.

    This tag enables Experience League to preserve the string in English when necessary. Meaning, the system knows if the product is not localized in Italian, for example. However, a customer might read Italian documentation on Experience League while using an English UI. In this case, your interface references remain in English to match the UI.

IMPORTANT

You must apply these tags prior to localizing your content.

See Applying DNL and UICONTROL to interface strings for guidance.

Writing with visuals (image assets, videos)

See Writing with visuals in the Spectrum guide for great information on how to effectively write for tutorial videos

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.

Another great resource is the Marketecture slide deck.

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.

Using Adobe in product names

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.

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 titles, headings, subheadings, and page navigation elements.
  • All words are lowercase except the first word and proper nouns, such as the names of brands, solutions, and services.
  • Match the capitalization in the product names of tools, options, menu items, dialog boxes, and fields.

Table of contents

The TOC.md is your table of contents. Each guide should have one.

Editorial guidance for a TOC

  • Capitalization: Always use sentence case for every entry (not including acronyms). Capitalize only formal product names or interface elements (pages, tabs, fields, options, and so on.). Match the UI when referring to it.
  • Verb form and parallelism: Use imperative verb and avoid gerunds. TOCs are lists so always try to keep lists parallel most of the time. There are exceptions that sometimes can’t be avoided. For conceptual pages, use nouns and noun phrases. For tasks, use verbs.

Syntax guidance

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

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.

Be positive in your 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.

Gender and inclusive language

See Gender and inclusive terminology.

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.

More help resources on Adobe editorial guidance

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

On this page