New Project Publication Checklist
This document describes what you need to do before you can make your new project documentation publicly available. There are some first-time tasks you must complete whenever you publish a new project.
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, please be sure to let the SSE team know at least two (2) weeks in advance. We have preparation items we need to perform before going live that we need to schedule for.
The following are the steps you need to take to make your documentation set available for the first time:
- Content check
- Soft launch
- Prepare for go live
- Go live
- After go live
If your project is coming from a migration, you would additionally have to clean up the migrated content, ensuring that it passes validation before publishing your content set. Contact the SSE team 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:
- 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.)
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
- 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
metadata.md file so that analytics can start running on your content. Add
type metadata so that your content can be filtered in search. the See Metadata for valid values.
- Update metadata (in either
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 2 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. This is where the public will interact with your repository. Reach out to SSE team to get this done. Turnaround is usually a few days.
- Change the link to the git repository to the newly created public git in
- 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 - SSE team takes care of this step once notified in the soft launch.
- Change index to
- Update hub pages to point to the new guide and new pages.
- Update goURLs, if applicable.
This is the day that material goes live.
- Re-activate pages - This ensures that your content is being indexed. Depending on repository size, this may happen a day before.
- Send out communication about the go live - SSE team 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 SSE team to push redirects for any content migrated from helpx.adobe.com or
After go live
Although some of the activities after the initial go live are pretty 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 SSE 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 SSECD with the Component Redirects.
- 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.