Clean-up tasks

Here are a few ways to improve the quality of your documentation.

Fix broken links

Address validation warnings for possible bad links

Jenkins validation jobs fail only if a relative link does not work. However, validation can pass even if absolute links are broken, if deep links have invalid anchor IDs, or if insecure URLs (http://) are used. It’s a good idea to go through the validation warnings for these links and resolve issues.

View this auto-updated report for a list of broken or problematic external links in your repo.

Edit links to previous help domain

Do a global search for marketing.adobe.com or helpx.adobe.com or docs.adobe.com links. Update the links. Use relative links if the target article is in the same repo as the source article. Use absolute links if the target article is outside the source article’s repo.

If there are links to marketing.adobe.com or docs.adobe.com that are still valid, please work with the Experience League team to migrate or move this content to a different location. Google search for this site is already turned off, and the site will eventually be decommissioned.

Evaluate top pages

You should receive an Adobe Analytics report once a month or so from the SSE team. (If you aren’t getting this PDF, contact the SSE team.) This analytics report includes data that you can use to improve your documentation. One action you can take is to look at which articles are getting the most traffic and make sure those articles are fulfilling users’ needs.

Open each highly viewed article and assess the following issues:

Do you have good SEO metadata?

Make sure your title and description follow search engine optimization guidance. See Title and description for SEO.

Is content up to date?

• Are screen shots out of date?
• Are there references to old technologies (such as DTM instead of Launch/Data Collection or Campaign Classic instead of Campaign v8 or Campaign Classic v7)?
• Are there links to missing/old content?

Is the article concise and comprehensive?

Does the article have a good overview, clear presentation of key tasks, and troubleshooting information where applicable? In other words, is it well written?

Is the article visually friendly?

If your article looks like a wall of text, consider adding an image, illustration, embedded video, or some other design element.

Also, be careful to avoid flooding your page with notes, tips, and important admonitions.

Is the article tagged for localization?

Make sure that the key terms in your user guides are tagged with [!UICONTROL] and [!DNL] tags so that translations into other languages are effective. See Localization.

Is the wrong article getting the most views?

In some cases, the wrong article is being promoted and is getting more views than a preferred article. If this occurs, contact the SSE team. We can figure out ways to demote and promote articles.

Are the Acrolinx scores good?

Run Acrolinx on the article and look for ways to improve the article.

Using analytics data in other ways

Checking the most popular articles for clarity and accuracy is just one way to improve documentation based on data. To learn about other methods, see Viewing Adobe Analytics reports.

Redesign your home page(s)

Consider improving the design of your user guide home pages.

See Designing the Home Page.

Use updated terminology

Do articles improperly refer to the “Marketing Cloud” instead of “Experience Cloud”? Do articles refer to “DTM,” “Launch,” “DPS,” or other end-of-life or rebranded products?

Add links to related solutions

Video tutorials

The Tech Marketing team has created an excellent set of video tutorials. Consider linking to these articles or embedded key videos in help articles.

See Video Tutorials

Other solutions

Refer to implementation topics in other solutions that might be useful to your users.

• If you link to deprecated features and products, edit these sections to include information about the newer feature.
• Edit out-of-date terminology that has been rebranded.
• Link to new solutions and features to improve SEO.

Check GitHub Issues and PRs

Both internal and external users can log issues and submit change requests for our documentation. Check the following:

• Are you receiving notifications for issues and pull requests for both the corporate git.corp.adobe.com/<repo> repo and the public gihub.com/<repo> mirror? Remember, the corporate and public repos have separate settings. See Sign up for GitHub notifications.

• Do you have unresolved issues or pull requests in either the Public or Corp repo?

  

• Is the public mirror in sync with the corporate repo? In some cases, the connection between the corporate and public repos becomes broken for different reasons. If this happens, let a member of the SSE team (Bob) know about it. We have a quick fix to reestablish the connection.

• Do you have permissions to close issues and pull requests? If not, let the SSE team (Bob) know.

See Work with GitHub Pull Requests and Issues.

Add localization tags

To improve the quality of machine-translated content, make sure that you add [!DNL] and [!UICONTROL] tags to solution names, feature names, and UI terms.

See Localization best practices for details. Also see Localization overview to background information about how we localize content.

Remove Unused Files

To keep your repo tidy, you can look at a report that displays unused files. This is especially useful for writers who save screenshots directly to the GitHub folder and iterate without removing previous versions. The Localization team still processes these files.

You can also run a Jenkins job that lets you easily remove all the unused assets.

1. Go to Jenkins > exl > your repo.

   https://docs.ci.corp.adobe.com/view/exl/

2. Click the unused.log file.

Run the RemoveUnusedContent job

Keep in mind that just because a file is unused does not necessarily mean that you want to delete it; it’s okay to keep files in your repo for a later or different use. That said, removing unused assets can help reduce Localization costs.

1. In GitHub Desktop, make sure that your repo clone is in sync with the server.

2. Consider creating a backup branch (such as backup-unused-nov2021) based on the main branch. This is an easy way to recover files you might end up wanting to use.

3. In Jenkins, run the RemoveUnusedContent job.

4. Click Build with Parameters, specify the solution and language, and click Build.

   A branch called __remove_unused_files is created. The unused files are removed in this branch.

   TIP

   If you want to keep one or more files, open the unused.log file in the __remove_unused_files branch. Add keep at the start of the line of each file you don’t want to remove. Save the unused.log file, and then re-run the RemoveUnusedContent job.

5. Create a pull request to remove the unused files.