Tutta la documentazione pubblica relativa ai prodotti Zendesk è pubblicata in questo Centro assistenza Zendesk. Sebbene la maggior parte degli altri team Zendesk crei contenuti direttamente nel centro assistenza, il team di Documenti crea e gestisce la documentazione del prodotto offline nei file sorgente DITA. DITA, acronimo di Darwin Information Typing Architecture, è un modello di dati basato su XML per la creazione e la pubblicazione di contenuti. Fondamentalmente, i file DITA sono file XML di solo testo.
Questo articolo include i seguenti argomenti:
Perché DITA?
DITA è uno standard del settore per la creazione e la gestione di set di documentazione di grandi dimensioni. È progettata per pubblicare contenuti su più canali da un’unica origine. Jacquie Samuels su techwhirl.com descrive il problema che tenta di risolvere come segue:
Scrivere contenuti in Word, email, PowerPoint, WordPress, HTML, InDesign, FrameMaker o qualsiasi altro formato è equivalente a scrivere su tavolette di pietra. I tuoi contenuti sono essenzialmente bloccati in quel formato e stupidi come un sasso. I contenuti stupidi non possono essere riutilizzati o riproposti facilmente, il che è inefficiente e costoso.
DITA è un modo di scrivere e memorizzare i contenuti in modo da poterli gestire come una risorsa. Sfrutta XML (eXtensible Markup Language) per rendere i tuoi contenuti intelligenti, versatili, gestibili e portabili.
Ad esempio, i contenuti DITA possono essere pubblicati (e completamente personalizzati) in PDF, HTML, RTF, PowerPoint e dispositivi mobili, il tutto senza dover copiare e incollare i file tra i file.
(Origine: Che cos’è DITA? su TechWhirl)
Oltre alla separazione tra contenuto e formato, gli altri vantaggi di DITA per il team di Zendesk Docs sono i seguenti:
- Ci costringe a essere disciplinati riguardo alla struttura dei contenuti. Un file DITA è XML. Se la struttura non è valida, lo strumento non ci permetterà di farci nulla.
- Ci permette di spostare facilmente i contenuti. Trasciniamo semplicemente un nodo di argomenti da un punto a un altro nella struttura.
- Ci permette di riutilizzare i contenuti importando parti di contenuti in più articoli.
- Non pubblichiamo spesso PDF, ma quando lo facciamo usiamo i file sorgente DITA.
Lo strumento di creazione DITA che usiamo è Oxygen XML Author. Oltre al suo solido ambiente di creazione, ci affidiamo a una miriade di altre funzionalità, tra cui la ricerca, la convalida e le trasformazioni XHTML. Altri strumenti di creazione DITA includono Framemaker, Arbortext e XMetal (solo per citarne alcuni).
Come creiamo e pubblichiamo gli articoli
Gli autori usano Oxygen XML Author per creare o aggiornare il contenuto dei file DITA. Poiché DITA è stato creato per consentire la pubblicazione multicanale da un'unica origine, i file di testo DITA non contengono stili. Contengono solo contenuto strutturato. Per il canale web, tutto lo stile viene fornito da fogli di stile CSS esterni, non da DITA. Nel nostro caso, tutto lo stile viene fornito dai fogli di stile nel tema Guide.
Quando siamo pronti per la pubblicazione (di solito durante il rilascio o l’aggiornamento di una funzione del prodotto), usiamo la funzione Autore per trasformare il codice DITA in XHTML, che è una versione più rigorosa di HTML. Quindi pubblichiamo il codice XHTML nel centro assistenza usando l' API del centro assistenza.
A partire dalla versione 24, l' Editor XML di Oxygen include uno scenario di trasformazione incorporato che può pubblicare argomenti DITA nell'output XHTML e caricarli direttamente come articoli in un centro assistenza Zendesk. Consulta Pubblicazione mappe di DITA nella guida dell’Editor XML. Per un video, consulta Pubblicazione di contenuti nel Centro assistenza Zendesk nella guida di Editor XML.
Di tanto in tanto, abbiamo bisogno di aggiornare molti articoli in un breve lasso di tempo. Ad esempio, quando Zendesk ha semplificato i prezzi e il branding, è stato necessario pubblicare centinaia di articoli modificati entro le 8:00 Fuso orario del Pacifico in una data specifica. Nelle settimane precedenti la scadenza, gli autori hanno aggiornato i file sorgente DITA, quindi abbiamo usato la funzione Autore per trasformare in batch i file. Li abbiamo trasferiti al centro assistenza usando l’API del centro assistenza. La pubblicazione ha richiesto solo pochi minuti.
Come gestiamo i file
Usiamo GitHub per gestire i nostri file DITA. Prima di creare o aggiornare un articolo, uno scrittore crea un branch nel nostro repository, apporta le modifiche e quindi crea una richiesta pull. La richiesta pull viene esaminata dagli altri autori del team. Questo ha l’ulteriore vantaggio di offrire agli autori l’opportunità di revisionare il lavoro degli altri.
Memorizziamo le immagini in Amazon S3, o Amazon Simple Storage Service, un servizio di memorizzazione nel cloud scalabile fornito da Amazon Web Services (AWS). Tutte le immagini nei nostri articoli vengono visualizzate nel browser da S3 e non dal centro assistenza. Il servizio Amazon S3 semplifica la gestione delle immagini.
Modalità di pubblicazione degli articoli localizzati
La lingua predefinita dei nostri centri assistenza è l’inglese. Pubblichiamo anche la documentazione del prodotto in tedesco, spagnolo, francese, giapponese, coreano, portoghese brasiliano, italiano e cinese semplificato.
Quando è necessario il trasferimento della localizzazione, usiamo l’API del centro assistenza per scaricare alcuni articoli in inglese dal centro assistenza e scriverli in file HTML. Usiamo l’API Amazon AWS per scaricare le immagini degli articoli dal nostro bucket Amazon S3. Imballiamo i file HTML e le immagini e li trasferiamo al nostro fornitore di localizzazione. Dopo che il fornitore ha restituito le traduzioni, noi carichiamo gli articoli e le immagini con l’API del Centro assistenza e l’API AWS.
Avvertenza sulla traduzione: questo articolo è stato tradotto usando un software di traduzione automatizzata per fornire una comprensione di base del contenuto. È stato fatto tutto il possibile per fornire una traduzione accurata, tuttavia Zendesk non garantisce l'accuratezza della traduzione.
Per qualsiasi dubbio sull'accuratezza delle informazioni contenute nell'articolo tradotto, fai riferimento alla versione inglese dell'articolo come versione ufficiale.