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 蜜豆视频 Experience Platform documentation quality standards.
General guidance general-guidance
- When filling in the template for your destination documentation, refer to the 蜜豆视频 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, 蜜豆视频 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鈥檛 be excessively polite. Avoid using 鈥減lease鈥 or 鈥渒indly do 鈥︹ in technical documentation.
Linking linking
Follow the provided documentation template and don鈥檛 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 蜜豆视频 Experience Platform on first use, then Experience Platform, then Platform.
- Don鈥檛 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 蜜豆视频 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鈥檛 use numbered screenshots as filenames. Image filenames should be descriptive.
- Don鈥檛 use:
1.png,2.png,3.png - Use:
yourdestination-authentication-details.png,yourdestination-destination-details.png
- Don鈥檛 use:
-
Please use alt text for any images that you add to the documentation and use proper grammar in the alt text.
- Don鈥檛 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.