New Project Publication Checklist

This document describes how to get started publishing to Experience League. Learn the high-level steps and where to go for answers about setting up your authoring environment and making your new documentation publicly available.

Set up your authoring environment

IMPORTANT

Budget commitments for localization might be required before deciding to publish to Experience League. The following steps familiarizes you with the decisions you will make prior to starting the authoring, migration, and publishing process.

To set up your authoring environment

  1. Get your project approved by meeting with:

    • Bob Bringhurst (technical lead)
    • Blake Frei (editorial lead)
    • Alva Ware-Bevacqui (content optimization)
    • Jeff Marques (localization)

    (Email to: Grp-Exl-Oboarding@adobe.com)

  2. Work with ExL Engineering to migrate your content (create the destination git repository, hook up validation). (Grp-Exl-Oboarding@adobe.com)

  3. If applicable, upload videos to Media Publishing Cloud (MPC).

  4. Add localization tags (UICONTROL, DNL). (Contact Blake Frei)

  5. Add metadata tags for SEO and content measurement.

  6. Provide product terminology and translation memories for localization.

  7. Add product term database to Acrolinx.

  8. Prepare to publish (content clean-up, soft launch, and so on).

  9. Hand off to localization.

  10. Continue authoring.

Localization requirements

Do not publish English content until the following conditions are met:

  • Authors have added Markdown localization tags. (See Localization best practices - UICONTROL and DNL)
  • Decisions have been made on languages required for your business needs if you require more languages that are currently supported.
  • Provide a list of product terminology that must remain in English (branded product names), as determined by your branding team.

Experience League currently publishes in all the following languages (no exceptions):

  • English
  • French
  • German
  • Japanese
  • Italian
  • Spanish
  • Brazilian Portuguese
  • Simplified Chinese
  • Traditional Chinese
  • Korean
  • Dutch
  • Swedish

If you require languages that are not currently supported, your product team is responsible for providing budget to add full language support to the platform. This can include items such as:

  • Experience League site localization (browser interface strings)
  • Experience League video localization
  • Machine translation engine training (depending on use case)

Setting up new language support is time consuming and can affect your release dates, depending on availability of machine translation engines, etc.

About machine translation

ExL content is machine-translated (MT) first. Meaning, all pages are localized using MT, then human translation can be done afterwards (based on budget). If your product is new, the localization group requires a list of terminology, including localization terms and any available translation memories. See Adobe’s machine translation wiki for more information.

Machine translated pages have a widget that allows users to display the original English content. Because the MT process is much quicker than human translation, it is likely that pages that frequently change are shown as machine-translated pages.

Not every language supported by the product has a custom MT engine on the market. All new customization requests must be discussed with the Globalization team. The Globalization team needs at least three months lead time to get an MT engine set up and customized. The budget to customize the engine(s) may need to be provided by the product team.

The cost of customizing an engine can vary greatly depending on the target language, available resources, and available training material.

Prepare to publish

This checklist assumes that you’ve created a new repository in git and have authored your pages in markdown and that you are ready to make your content available.

IMPORTANT

Before your project goes live, complete the steps described above and provide a lead time of at least two (2) weeks in advance.

After you migrate or create content, the following tasks are required to make your documentation available for the first time:

  • Content check
  • Soft launch
  • Prepare for go live
  • Go live
  • After go live
NOTE

If your project is coming from a migration, you need to clean up the migrated content, ensuring that it passes validation before publishing your content set. Contact the Bob Bringhurst for information on the steps needed to clean up your repository in a migration.

Content check

Before you perform a soft launch, ensure that you do the following:

  • If you haven’t already done so, copy the necessary “front matter” files from a different repo. See User Guide Setup: Repo Files.
  • Add a landing page (home.md) to your guide. Your guide must have an introductory page. This should be the first article in your TOC.md file. In user guides, this file includes a summary of the solution and user guide, links to other solution user guides (if applicable), and links to useful resources such as community and learning resources.
  • Check the metadata.md and TOC.md files to make sure that your metadata values and anchor IDs are appropriate.
  • To avoid causing unnecessary changes to article URLs, nail down your TOC structure, your filenames, and the anchor IDs you use in the TOC.md file. For example, if you change an anchor ID, the URLs of the articles in that section will also change.
  • In each article, make sure the required metadata is populated.
  • For the soft launch, change the index to n so Google cannot find the pages when you publish them. (You’ll want to change this to y later a day or so prior to hard launch.)

Soft launch

A soft launch means publishing your content on the production server (experienceleague.adobe.com) without indexing it in Google. You can only do this after your content is validated in Jenkins and you can preview in experienceleague.adobe.com.

  • Activate the pages to see the output (use the activate-exl job in Jenkins.) Be sure your index is set to no or n.
  • Check the soft-launched materials in experienceleague.corp.adobe.com and continue clean-up.
  • Clean up anything that looks “bad” - wonky tables, asterisks instead of bold, steps that number improperly, special characters that don’t display properly, and so on.
  • Check that your left-rail appears as you want it to. If not, change the TOC. (If you do have redirects, then be sure to update that sheet based on your changes to the TOC.)
  • Add the product metadata item for your product in either the TOC.md or metadata.md file so that analytics can start running on your content. Add solution and type metadata so that your content can be filtered in search. the See Metadata for valid values.
  • Update metadata (in either TOC.md or metadata.md) to change the header links to point to appropriate content for hub page, getting started, and tutorials.

Prepare for go live

Preparing for go live can take up to two weeks if you are redirecting from helpx. If you have no redirects, this can take considerably less time.

  • Set up the public github mirror on github.com. The public git hub is where the public interacts with your repository. Reach out to ExL Engineering to set up the public git hub. Turnaround is usually a few days.
  • Change the link to the git repository to the newly created public git in metadata.md.
  • Subscribe to the public git repository - If you do not sign up for notification, you will miss pull requests and issues logged in a repository.
  • If applicable, submit redirect sheet to web ops - engineering takes care of this step once notified in the soft launch.
  • Change index to y globally.
  • Update hub pages to point to the new guide and new pages.
  • Update goURLs, if applicable.

Go live

This is the day that material goes live.

  • Reactivate pages - Reactivating ensures that your content is being indexed. Depending on repository size, this process may happen a day before.
  • Send out communication about the go live - ExL Engineering handles this. Please provide us with a list of distribution lists or people that you want this communicated to.
  • Publish any link updates to your hub pages.
  • Ask engineering to push redirects for any content migrated from helpx.adobe.com or marketing.adobe.com.

After go-live

Although some of the activities after the initial go live are self-explanatory, such as cleaning up any errors or fixing any links to pages you missed, a few are specific to documents that are in our system:

  • Submit the sitemap, remove old URLS (if applicable), and add info to robots.txt file - these activities help you with your documentation set’s SEO - This is something the engineering team handles within a week of the go live date. You do not need to do anything for this to happen.
  • If applicable, resubmit incorrect redirects. Please open bugs in Project UGP.
  • Push pull requests from public git to private git - if pull requests come into your public git repository, please let us know and we will copy it into the corporate git repository. We are working on a solution where this happens automatically in the future.
  • Respond to public git issues and pull requests in a timely manner - you decide how to handle outside contributions within your group.

What’s next

After your content is live, editing and publishing is straightforward if you understand Git Hub and Markdown. Generally, the authoring and editing process is as follows:

  1. In Git Desktop, update your local repo (pull updates, clone an existing one).
  2. In Git Desktop, click Open in Visual Studio Code.
  3. Navigate to the page you want to edit, and begin working. (See the Authoring Style Guide for editorial guidance. See Markdown Syntax for Markdown help.)

On this page