Best practice di authoring
Panoramica overview
Questa pagina descrive le regole da seguire per creare la documentazione di destinazione per assicurarsi che soddisfi gli standard di qualità della documentazione di Adobe Experience Platform.
Indicazioni generali general-guidance
- Durante la compilazione del modello per la documentazione di destinazione, consulta la guida per i collaboratori Adobe per informazioni su collegamenti, tabelle, sintassi markdown supportata, istruzioni per la scrittura e altro ancora.
- Non includere osservazioni e stime nella documentazione del prodotto.
- Nella documentazione di Experience Platform, gli autori di Adobi utilizzano la formattazione in grassetto per fare riferimento ai controlli dell'interfaccia utente, come riportato di seguito:
- Vai a Connessioni > Destinazioni e seleziona la scheda Catalogo. Visualizza un esempio di come i controlli dell'interfaccia utente sono documentati in un tutorial sulle destinazioni.
Stile scrittura
- Mantieni le tue frasi brevi e arriva rapidamente al punto. Se la tua frase è lunga più di 20 parole o utilizza più virgole, prendi in considerazione di suddividerla in frasi separate. Frasi di lunghezza superiore a 20 parole possono essere particolarmente difficili per i lettori.
- Non siate eccessivamente educate. Evita di utilizzare "per favore" o "gentilmente fare …" nella documentazione tecnica.
Collegamento linking
Segui il modello di documentazione fornito e non modificare i collegamenti esistenti nel modello. Quando si includono nuovi collegamenti, leggere Utilizzo dei collegamenti nella documentazione nella guida per i collaboratori.
Linee guida per il branding branding
-
AEP non è un termine approvato rivolto al pubblico. Utilizza Adobe Experience Platform al primo utilizzo, quindi Experience Platform e infine Platform.
- Non utilizzare: prima di esportare i dati da AEP a YourDestination, assicurati di aver letto e completato questi prerequisiti.
- Utilizza: prima di esportare dati da Adobe Experience Platform a YourDestination, assicurati di aver letto e completato questi prerequisiti.
Immagini e schermate images-and-screenshots
-
Per informazioni su come collegarsi alle immagini, fare riferimento alla Guida per i collaboratori.
-
Quando utilizzi le schermate, accertati che queste acquisiscano l’intera schermata dell’interfaccia utente di Platform.
-
Quando si marcano le immagini per evidenziare un determinato controllo o etichetta nella pagina, provare a seguire lo stile di markup utilizzato dal team di documentazione di Experience Platform. Osserva come la schermata basata sul profilo è evidenziata in questa schermata.
-
Utilizzare immagini in formato
png. -
Non utilizzare le schermate numerate come nomi di file. I nomi dei file immagine devono essere descrittivi.
- Non utilizzare:
1.png,2.png,3.png - Usa:
yourdestination-authentication-details.png,yourdestination-destination-details.png
- Non utilizzare:
-
Utilizza il testo alternativo per tutte le immagini aggiunte alla documentazione e utilizza la grammatica corretta nel testo alternativo.
- Non utilizzare: dettagli della connessione di destinazione
- Usa: immagine dell'interfaccia utente di Platform che mostra i dettagli della connessione di destinazione compilati.
Processo process
- Il modello di documentazione viene aggiornato raramente, in base al feedback del partner. Prima di iniziare a creare la documentazione per la destinazione, assicurati di aver scaricato la versione più recente del modello.
- Crea la documentazione e crea la richiesta di pull della documentazione (PR) da un ramo nel fork diverso dal ramo principale. Consulta la sezione relativa alla destinazione di invio per la revisione durante la creazione nell'interfaccia GitHub o nell'ambiente locale.