Authoring Guide for Adobe Writers

banner

Please note, this content is intended only for Adobe employees. If you are not an Adobe employee, see the Adobe Contributor Guide.

Searchable list of articles

TIP

We’re still working on allowing this guide to be searched in experienceleague.adobe.com without making it public. In the meantime, you can search within this page to find the article for which you’re looking.

Article Description and Keywords
What’s new in this guide List of new articles and significant changes.
Getting started overview Learn how to author and publish Experience League content.
Git setup How Adobe contributors should set up Git, GitHub Desktop, and other tools
Git and GitHub documentation essentials This article explains an overview of Git, GitHub repository, how content is organized, and naming conventions used for Adobe documentation.
Workflow for Adobe leads How Adobe lead writers should work in GitHub, Visual Studio Code, and Jenkins.
Workflow for infrequent contributors Learn different methods for logging issues and editing content.
Fix validation errors How to resolve validation errors in the Jenkins pipeline, including validation summaries in pull requests and Slack. Validation errors include Git conflicts, illegal characters, BOM characters, package and structure, link check.
Preview and publish content Push or activate content to go live. Set up auto-activate.
User guide setup What Adobe lead writers should know about user guide setup in Git.
  • Adobe Docs repo structure
  • Required repo files
  • User guide files (TOC.md file) and home page
  • Naming files and folders
  • How URLs are generated
  • Landing pages and breadcrumbs
    Working with TOC.md files How to work with Table of Contents files to determine what appears in left nav of user guide.
    Designing the home page Best practices for designing the home page of the user guide. Use a template for the home page.
    Creating and configuring repos Create a repository, add required files, and configure new Jenkins jobs for pushing content live
    New project publication checklist Guidance and best practices for creating a new repo in AdobeDocs
    Deleting repositories and deactivating content How to remove repositories
    Markdown syntax guide A basic introduction to Markdown styling. Page elements: Block quotes, Escape characters, Code Blocks, Code Blocks with line numbering, Definition Lists, Download Files, Headings, Images, Links and Cross-References, Metadata, Image Links, Numbered Lists, Bullet Lists, Comments, Tables, Notes, Tips, Important, Video, More Like This, CONTEXTUALHELP
    Markdown syntax cheatsheet Quick overview of supported Markdown syntax for Adobe documentation.
    Working with tables Working with markdown tables and HTML tables.
    Adding links Linking tips
    Authoring best practices Guidance and best practices for writing in Visual Studio Code.
    • Prevent common errors
    • Visual Studio Code tips
    • Adobe Markdown Authoring extension for VSC
    • Visual Studio Code add-ons
    • Global Find/Replace and wildcard expression searches
    Authoring style guide and SEO for Experience Cloud writers A quick reference for Experience Cloud authoring standards. Includes guidance on:
    • Active voice
    • Tense
    • Gender and inclusive language
    • Procedures
    • Branding
    • First paragraphs
    • Capitalization
    • Word choice and spelling
    • Tables of contents, and more
    Create a page in Experience League Learn how to author a page in Experience league, add metadata, headings, paragraphs, and more.
    Authoring landing page descriptions How to write landing page descriptions.
    Video A quick reference for creating and uploading video tutorials to Experience League. AdobeTV and MPC.
    Content types in Experience League documentation Learn about guide definitions and content types in technical writing.
    Steps and lists Learn editorial guidance on steps and sub-steps technical writing.
    Heading names and page titles Guidance and best practices for writing headings for concepts, tasks, and page titles
    Titles and descriptions for SEO How to write titles and descriptions to optimize search.
    Acrolinx How to use Acrolinx to check spelling, usage, and terminology.
    Improving search results Learn how to improve search results both internally and externally (that is, Google) in Adobe documentation.
    Table of contents authoring Guidance and best practices for creating a TOC
    Moving and restructuring content Learn best practices and consequences of moving and renaming files and folders in Git, and of restructuring content in the TOC.
    Staging review content How to create a review branch for previewing content and staging a review
    GitHub pull requests Learn to manage public github.com pull requests and logged issues. Information about public github.com mirrors.
    Hiding files Hide files, sections, or entire guides from search engines or in the TOC or both.
    Cleanup tasks Clean-up tasks for writers to perform
    Metadata How to use metadata and tags for AdobeDocs. Information about where to add metadata and metadata hierarchy. Common tags: solution, product, role, level, feature, feature-set, topic, title, description, exl-id, git-repo, mini-toc-levels, hide, hidefromtoc, index, internal.
    Redirects Adding redirects for previous domains or for different locations within experienceleague.adobe.com
    Microsites A microsite is an HTML website that is uploaded to Experience League directly instead of through the standard authoring pipeline. Microsites are useful for displaying HTML sample files or providing tools or services not available through markdown authoring.
    Rename the git default branch Follow these steps to rename the master branch to the main branch.
    Create contextual help Learn how to set up content for contextual help popovers that can appear in the Experience Cloud product UI.
    Landing pages Understand how landing pages are generated. Understand the different syntax and validation rules.
    Localization overview Localization Overview
    Applying DNL and UICONTROL to interface strings Applying DNL and UICONTROL to interface strings
    Writer resources Learning resources for Git and GitHub, GoURLs or go urls, upload videos to AdobeTV/MPC, Slack channels, list of writers, design resources, logging jira tickets.
    Optimize content for Analytics Learn how to add metadata to ensure optimal Analytics data. Get tips for viewing reports.
    Collapsible sections (accordions) You can create a collapsible section (sometimes called an accordion) that is hidden by default. The user can click the title to expand or collapse the section.
    Snippets and includes Use snippets or includes to share text among articles in a repo.
    Courses In-progress documentation for creating defining courses, lessons, and awards, not to mention skills and guides.
    Lead Main editing workflow for lead writers.

    		Infrequent Not a lead writer? Learn the easiest ways to make contributions.

    		Validation Learn to resolve validation errors.

    More Resources

    On this page