Tutta la documentazione pubblica sui prodotti per Zendesk è pubblicata in questo centro assistenza Zendesk. Sebbene la maggior parte degli altri team di Zendesk crei contenuti direttamente nel centro assistenza, il team di Documenti crea e conserva la documentazione del prodotto offline nei file di origine DITA. DITA, acronimo di Document 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 testo normale.
Questo articolo include i seguenti argomenti:
Perché DITA?
DITA è uno standard del settore per la creazione e la gestione di insiemi di documentazione di grandi dimensioni. È progettato per pubblicare contenuti in 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 equivale 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 riutilizzati facilmente, il che è inefficiente e costoso.
DITA è un modo per scrivere e archiviare 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 in DITA possono essere pubblicati (e completamente personalizzati) in PDF, HTML, RTF, PowerPoint e dispositivi mobili, il tutto senza dover copiare e incollare nulla tra i file.
(Origine: Che cos’è DITA? su TechWhirl)
Oltre alla separazione del contenuto dal formato, gli altri vantaggi di DITA per il team di Documenti Zendesk 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 consentirà di farci nulla.
- Ci permette di spostare facilmente i contenuti. Trasciniamo semplicemente un nodo argomento da un punto all’altro della struttura.
- Ci permette di riutilizzare i contenuti importando porzioni di contenuti in più articoli.
- Non pubblichiamo spesso PDF, ma quando lo facciamo usiamo i file di origine DITA.
Lo strumento di creazione DITA che usiamo è Oxygen XML Author. Oltre al suo solido ambiente di creazione, ci affidiamo a una serie di altre funzionalità, tra cui ricerca, convalida e trasformazioni XHTML. Altri strumenti di creazione DITA includono Framemaker, Arbortext e XMetal (solo per citarne alcuni).
Come creiamo e pubblichiamo articoli
Gli autori usano Oxygen XML Author per creare o aggiornare il contenuto nei file DITA. Poiché DITA è stato creato per consentire la pubblicazione multicanale da un'unica origine, i file di testo DITA non contengono stili. Tutto ciò che contengono è 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 è fornito dai fogli di stile nel tema del nostro centro assistenza .
Quando siamo pronti per la pubblicazione (di solito nello stesso momento in cui una funzione del prodotto viene rilasciata o aggiornata), usiamo Autore per trasformare DITA in XHTML, che è una versione più rigida di HTML. Quindi pubblichiamo l’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 integrato in grado di pubblicare argomenti DITA nell’output XHTML e caricarli direttamente come articoli in un centro assistenza Zendesk . Consulta la guida di Pubblicazione mappe DITA nell’editor XML. Per un video, consulta Pubblicazione di contenuti nel centro assistenza Zendesk nella guida di Editor XML.
A volte, 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 Ora del Pacifico in una data specifica. Nelle settimane precedenti la scadenza, gli autori hanno aggiornato i file di origine DITA, quindi abbiamo usato Autore per trasformare i file in batch. Li abbiamo inviati 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, 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 esaminare reciprocamente il lavoro.
Archiviamo le immagini in Amazon S3o Amazon Simple Storage Service, un servizio di archiviazione cloud scalabile fornito da Amazon Web Services (AWS). Tutte le immagini nei nostri articoli vengono pubblicate sul browser da S3, non dal centro assistenza. Il servizio Amazon S3 semplifica la gestione delle immagini.
Come pubblichiamo gli articoli localizzati
La lingua predefinita dei nostri centri assistenza è l’inglese. I documenti dei prodotti sono pubblicati anche in tedesco, spagnolo, francese, giapponese, coreano, portoghese brasiliano, italiano e cinese semplificato.
Quando è necessario il trasferimento della localizzazione, usiamo l’API 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. I file HTML e le immagini vengono compressi e li trasferiamo al nostro fornitore di localizzazione. Dopo che il fornitore ha restituito le traduzioni, 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.
0 commenti