Authoring best practices
Overview overview
This page describes rules that you should follow when authoring your destination documentation page, to ensure that it meets the Adobe Experience Platform documentation quality standards.
General guidance general-guidance
- When filling in the template for your destination documentation, refer to the Adobe contributor guide for information about linking, tables, the supported markdown syntax, writing guidance, and more.
- Do not include observations and estimations in the product documentation.
- In Experience Platform documentation, Adobe writers use bold formatting to refer to user interface controls, like this:
- Go to Connections > Destinations, and select the Catalog tab. View an example of how user interface controls are documented in a destinations tutorial.
Writing style
- Keep your sentences short and get to the point fast. If your sentence is over 20 words long or uses multiple commas, consider breaking it up into separate sentences. Sentences over 20 words in length can be especially challenging for readers.
- Don’t be excessively polite. Avoid using “please” or “kindly do …” in technical documentation.
Linking linking
Follow the provided documentation template and don’t edit the existing links in the template. When including new links, read using links in documentation in the contributor guide.
Branding guidelines branding
-
AEP is not an approved public-facing term. Please use Adobe Experience Platform on first use, then Experience Platform, then Platform.
- Don’t use: Before you can export data from AEP to YourDestination, make sure you read and complete these prerequisites.
- Use: Before you can export data from Adobe Experience Platform to YourDestination, make sure you read and complete these prerequisites.
Images and screenshots images-and-screenshots
-
For information on how to link to images, refer to the contributor guide.
-
When using screenshots, please ensure that your screenshot captures the entire Platform UI screen.
-
When marking up images to highlight a certain control or label on the page, try to follow the markup style used by the Experience Platform documentation team. Notice how Profile-based is highlighted in this screenshot.
-
Please use
pngformat images. -
Please don’t use numbered screenshots as filenames. Image filenames should be descriptive.
- Don’t use:
1.png,2.png,3.png - Use:
yourdestination-authentication-details.png,yourdestination-destination-details.png
- Don’t use:
-
Please use alt text for any images that you add to the documentation and use proper grammar in the alt text.
- Don’t use: Destination connection details
- Use: Image of the Platform UI, showing destination connection details filled in.
Process process
- The documentation template is updated infrequently, based on partner feedback. Before you begin authoring documentation for your destination, make sure that you have downloaded the latest version of the template.
- Author the documentation and create the documentation pull request (PR) from a branch in your fork other than the main branch. Refer to the submit destination for review section when authoring in the GitHub interface or in your local environment.