App vendor checks

The App migration platform provides the ‘App vendor checks’ feature in the Cloud Migration Assistant (CMA) that allows you to run pre-migration checks on your customer’s instance, surface warnings and provide resolution instructions before they run their migration.

The image below provides a sample preview of what the App vendor check feature looks like in the CMA.

How do app vendor checks help app migration?

When customers run their migration, they may face scenarios where the migration is blocked due to errors that occur while migrating apps. Current research shows that the issues that cause a large percentage of failed app migrations can be detected before the customer runs the migration. Detecting problems early reduces customer frustration, and reduces the chances of them being blocked by errors that can be resolved easily.

As an app vendor / Marketplace Partner, you play a crucial role in predicting the scenarios that can cause errors and block customers when they try to migrate your app to Cloud.

This page provides guidance on writing effective and easy-to-comprehend warning messages and resolution instructions in the CMA, so that the app migration becomes smoother for both you and the customer. Read our docs for technical information on how to build app vendor checks.

Visualising app vendor checks in the Cloud Migration Assistant

App vendor checks are messages that you can surface in the customer’s instances of the CMA, after running your check for potential issues that can cause failure while migrating your app to Cloud. See an example below of what the new 'App vendor check' screen looks like in the CMA.

How to write effective app vendor checks

The purpose of writing app vendor check messages is to:

• flag potential errors/warnings to customers that can fail an app migration before they migrate
• surface specific instructions to customers on how to fix warnings before running the migration

A check has 2 parts:

• Title
• Body

In order to create effective messages, consider the guidelines that follow.

Title

Create an informative title that summarizes the scenario. For warning messages, summarise the issue in the title so that your customer can understand the problem just by reading the title alone. You can provide details about the issue and the workaround in the body of the check.

See a few examples of titles in the table below.

Body

In most cases, this should be a step-by-step instructional guide on how customers can fix the error before proceeding with the migration. Your job is to provide customers with simple and easy to understand instructions to proceed with the migration. Avoid overwhelming customers with technical details unless absolutely necessary.

The body copy is divided into two parts:

1. A paragraph or sentence preceding the steps. The character limit for a paragraph or the sentence is 180 characters.

2. The steps to fix warning/error In any error state, it’s best to limit the number of steps to 5 or fewer. The character count for each step is 175 characters.

Best practices for writing body content

• Content clarity: Keep content as short and concise as possible, particularly if you're providing step-by-step instructions. See an example below.

  Good	Avoid
  Click 'Open app preferences' below.	First, you need to click ‘Open app preferences’ below.

• American English: Atlassian follows the American English rules of spelling for written content in products. It is recommended you follow the same language rules to maintain consistency of content in the CMA.

• Commas:

  • In lists of three or more things, include the comma before words like 'and' or 'or'. See an example below.

  Good	Avoid
  Read product-related data like pages, sites, issues, and projects.	Read product-related data like pages, sites, issues and projects.

  • Use a comma after an introductory phrases like 'For example' or 'First'. See an example below.

  Good	Avoid
  First, select 'Preferences' under ‘Settings’.	First select 'Preferences' under 'Settings'.

• Capitalization: Here are a few guideslines on how to capitalize titles and copy:

  • Always use sentence case for text, headings, and page titles. Capitalize the first letter of the first word, as well as any proper nouns or names. See an example below.

  Good	Avoid
  Remove undefined custom fields	Remove Undefined Custom Fields remove undefined custom fields

  • Capitalize the first letter of text on buttons. The remaining text can remain in sentence case. See an example below.

  Good	Avoid
  Open app preferences.	Open App Preferences.

• Use of 'you' and 'your'

  • Instead of writing about customers in general, write to your reader directly as if you are speaking to them. Refer to the reader as 'you' and tell them what to do directly. See an example below.

  Good	Avoid
  Remove custom fields in order to migrate. You can edit this after the migration in your Cloud site.	Remove custom fields in order to migrate. This can be edited after the migration in the Cloud site.

• Use active voice over passive voice

  • Active voice makes your writing easy to understand, particularly if you're writing instructions or a step-by-step guide for customers. This means that the subject (customers) performs the action (the verb). Sentences written in active voice also ensure brevity of sentences, making your writing easier to read. See an example below.

  Good	Avoid
  Remove custom fields in order to migrate.	Custom fields need to be removed in order to migrate.

More resources

To better organize your content and write good app vendor check message copy, refer to the resources listed below:

• General writing guidelines: https://atlassian.design/content/writing-guidelines/
• Guidelines to writing warning messages: https://atlassian.design/content/writing-guidelines/writing-a-warning-message