If you’re have never authored in Experience League, or you want to migrate from another source (like Helpx), there is important planning you need to do. This document describes who to talk to, how to set up your authoring environment, and what to do before making your new documentation publicly available.
Get your project approved by meeting with:
Experience League provides the following types of content for customers:
|Product documentation||Product help (feature user guides) authored by technical writers on product teams.
The primary tools used are Visual Studio Code (Markdown) and GitHub. Content is published out of Jenkins.
|Tutorials (Video and articles)||Tutorials are video and text-based guides authored by Technical Marketing.
The primary tools used are Visual Studio Code (Markdown), GitHub, and MPC for video uploads. Content is published out of Jenkins.
|Courses||Courses are Adobe expert-curated collections of content, typically comprised of multiple lessons to educate users about a broad area, use case, or product (like implementation, user fundamentals).
The primary tools used are Jira, MPC (for initial video upload), and Markdown/GitHub. Reach out to Sean Schnoor for publishing courses.
See Content Types for deeper definitions of deliverables on Experience League.
If you are creating courses or video tutorials, you’ll need to upload each video and get the associated ID for the URLs used in courses and product documentation.
See Video to learn about getting started creating courses and tutorials. Return here for information about setting up your GitHub/Markdown environment.
Here’s where writers can find tools and useful information about Experience League authoring:
|Adobe Doc Github Repo||GitHub is our content management system. You’ll need a github account to access this repo.|
|Visual studio code||VSC is our recommended Markdown authoring tool.|
|Jenkins||The publication and validation system.|
|Authoring guide||The published version of this guide.|
|Experience League landing||The landing page for Experience League (Adobe’s enterprise help portal).|
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
Do not publish English content until the following conditions are met:
Experience League currently publishes in all the following languages (no exceptions):
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:
Setting up new language support is time consuming and can affect your release dates, depending on availability of machine translation engines, etc.
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.
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.
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:
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.
Before you perform a soft launch, ensure that you do the following:
(home.md)to your guide. Your guide must have an introductory page. This should be the first article in your
TOC.mdfile. 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.
nso Google cannot find the pages when you publish them. (You’ll want to change this to
ylater a day or so prior to hard 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
activate-exljob in Jenkins.) Be sure your index is set to
experienceleague.corp.adobe.comand continue clean-up.
productmetadata item for your product in either the
metadata.mdfile so that analytics can start running on your content. Add
typemetadata so that your content can be filtered in search. the See Metadata for valid values.
metadata.md) to change the header links to point to appropriate content for hub page, getting started, and tutorials.
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.
This is the day that material goes 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:
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: