Prácticas recomendadas de creación
Información general overview
En esta página se describen las reglas que debe seguir al crear su página dedocumentación de destino para asegurarse de que cumple los estándares de calidad de la documentación de Adobe Experience Platform.
Directrices generales general-guidance
- Al rellenar la plantilla para la documentación de destino, consulte la guía del colaborador de Adobe para obtener información sobre vinculación, tablas, la sintaxis de markdown admitida, instrucciones de escritura y más.
- No incluya observaciones y estimaciones en la documentación del producto.
- En la documentación del Experience Platform, los escritores de Adobe usan formato de negrita para hacer referencia a los controles de la interfaz de usuario, de esta manera:
- Vaya a Conexiones > Destinos y seleccione la ficha Catálogo. Vea un ejemplo de cómo se documentan los controles de la interfaz de usuario en un tutorial de destinos.
Estilo de escritura
- Mantén tus frases cortas y ve al grano rápidamente. Si tu frase tiene más de 20 palabras o usa múltiples comas, considera separarla en oraciones separadas. Las frases de más de 20 palabras pueden ser especialmente difíciles para los lectores.
- No seas excesivamente educado. Evite utilizar "por favor" o "amablemente haga…" en la documentación técnica.
Vinculación linking
Siga la plantilla de documentación proporcionada y no edite los vínculos existentes en la plantilla. Cuando incluya nuevos vínculos, lea usando vínculos en la documentación de la guía del colaborador.
Directrices de marca branding
-
AEP no es un término público aprobado. Utilice Adobe Experience Platform en el primer uso, luego Experience Platform y luego Platform.
- No uses: Para poder exportar datos de AEP a tu destino, asegúrate de leer y completar estos requisitos previos.
- Usar: para poder exportar datos de Adobe Experience Platform a tu destino, asegúrate de leer y completar estos requisitos previos.
Imágenes y capturas de pantalla images-and-screenshots
-
Para obtener información sobre cómo vincular a imágenes, consulte la guía del colaborador.
-
Cuando utilice capturas de pantalla, asegúrese de que la captura de pantalla capture toda la pantalla de la interfaz de usuario de Platform.
-
Al marcar imágenes para resaltar un control o una etiqueta determinados en la página, intente seguir el estilo de marcado utilizado por el equipo de documentación del Experience Platform. Observe cómo Basado en perfiles se resalta en esta captura de pantalla.
-
Utilice
pngimágenes de formato. -
No utilice capturas de pantalla numeradas como nombres de archivo. Los nombres de archivo de imagen deben ser descriptivos.
- No use:
1.png,2.png,3.png - Usar:
yourdestination-authentication-details.png,yourdestination-destination-details.png
- No use:
-
Utilice texto alternativo para cualquier imagen que agregue a la documentación y utilice la gramática adecuada en el texto alternativo.
- No usar: detalles de conexión de destino
- Usar: imagen de la interfaz de usuario de Platform que muestra los detalles de conexión de destino rellenados.
Proceso process
- La plantilla de documentación se actualiza con poca frecuencia, según los comentarios del socio. Antes de empezar a crear documentación para tu destino, asegúrate de haber descargado la última versión de la plantilla.
- Cree la documentación y la solicitud de extracción de documentación (PR) a partir de una rama de su ramificación distinta de la rama principal. Consulte la sección enviar destino para revisión cuando cree en la interfaz de GitHub o en su entorno local.