Práticas recomendadas de criação
Visão geral overview
Esta página descreve as regras que você deve seguir ao criar sua documentação de destino para garantir que ela atenda aos padrões de qualidade da documentação do Adobe Experience Platform.
Orientações gerais general-guidance
- Ao preencher o modelo da documentação de destino, consulte o guia do colaborador do Adobe para obter informações sobre vinculação, tabelas, a sintaxe de Markdown compatível, orientação de escrita e muito mais.
- Não inclua observações e estimativas na documentação do produto.
- Na documentação do Experience Platform, os escritores de Adobe usam a formatação em negrito para se referir aos controles da interface do usuário, desta forma:
- Vá para Conexões > Destinos e selecione a guia Catálogo. Veja um exemplo de como os controles da interface do usuário são documentados em um tutorial de destinos.
Estilo de escrita
- Mantenha suas frases curtas e vá direto ao ponto. Se a sua frase contiver mais de 20 palavras ou usar várias vírgulas, considere dividi-la em frases separadas. Frases com mais de 20 palavras podem ser especialmente desafiadoras para os leitores.
- Não seja excessivamente educado. Evite usar "favor" ou "gentilmente faça …" na documentação técnica.
Vinculação linking
Siga o modelo de documentação fornecido e não edite os links existentes no modelo. Ao incluir novos links, leia usando links na documentação no guia do colaborador.
Diretrizes de marca branding
-
AEP não é um termo aprovado voltado para o público. Use o Adobe Experience Platform na primeira utilização, depois o Experience Platform e, por fim, a Platform.
- Não usar: antes de exportar dados do AEP para seu destino, leia e conclua esses pré-requisitos.
- Uso: antes de exportar dados do Adobe Experience Platform para o Seu Destino, leia e conclua esses pré-requisitos.
Imagens e capturas de tela images-and-screenshots
-
Para obter informações sobre como vincular a imagens, consulte o guia do colaborador.
-
Ao usar capturas de tela, certifique-se de que sua captura de tela capture toda a tela da interface do usuário da plataforma.
-
Ao marcar as imagens para destacar um determinado controle ou rótulo na página, tente seguir o estilo de marcação usado pela equipe de documentação do Experience Platform. Observe como Baseado em perfil é realçado em esta captura de tela.
-
Use imagens no formato
png. -
Não use capturas de tela numeradas como nomes de arquivo. Os nomes de arquivo de imagem devem ser descritivos.
- Não usar:
1.png,2.png,3.png - Uso:
yourdestination-authentication-details.png,yourdestination-destination-details.png
- Não usar:
-
Use o texto alternativo para quaisquer imagens adicionadas à documentação e use a gramática apropriada no texto alternativo.
- Não usar: detalhes da conexão de destino
- Uso: imagem da interface do usuário da Platform, mostrando os detalhes da conexão de destino preenchidos.
Processo process
- O modelo de documentação é atualizado com pouca frequência, com base no feedback do parceiro. Antes de começar a criar a documentação para o seu destino, baixe a última versão do modelo.
- Crie a documentação e crie a solicitação de pull (PR) de documentação de uma ramificação na sua bifurcação diferente da ramificação principal. Consulte a seção destino de envio para revisão ao criar na interface do GitHub ou em seu ambiente local.