Toute la documentation produits Zendesk destinée au public est publiée dans ce centre d’aide Zendesk. La plupart des autres équipes Zendesk créent le contenu directement dans le centre d’aide, mais l’équipe chargée de la documentation produits en assure la création et la maintenance hors ligne, dans des fichiers sources DITA. DITA (Darwin Information Typing Architecture) est un modèle de données basé sur XML pour la création et la publication de contenu. En fait, les fichiers DITA sont des fichiers XML en texte brut.
Cet article aborde les sujets suivants :
Pourquoi DITA ?
DITA est une norme du secteur pour la création et la maintenance des ensembles de documents volumineux. Elle est conçue pour la publication de contenu sur plusieurs canaux à partir d’une source unique. Jacquie Samuels, sur techwhirl.com, décrit le problème que DITA essaie de résoudre comme suit :
La rédaction de contenu dans Word, la messagerie, PowerPoint, WordPress, HTML, InDesign, FrameMaker ou tout autre format revient à écrire sur des tablettes de pierre. Votre contenu est plus ou moins limité à ce format et difficile à exploiter ou à réutiliser, ce qui est inefficace et coûteux.
Avec DITA, vous pouvez rédiger et stocker votre contenu d’une façon qui vous permet de le gérer comme un actif. DITA s’appuie sur XML (eXtensible Markup Language) pour que votre contenu soit intelligent, polyvalent, gérable et portable.
Par exemple, le contenu créé dans DITA peut être publié au format PDF, HTML, RTF, PowerPoint et mobile, sans effectuer le moindre copier-coller d’un fichier à un autre.
(Source : Qu’est-ce que DITA ? sur TechWhirl)
En plus de la séparation du contenu et du format, les autres avantages de DITA pour l’équipe Zendesk chargée de la documentation sont les suivants :
- Nous impose une certaine discipline pour la structure du contenu. Un fichier DITA est au format XML. Si la structure n’est pas valide, l’outil nous empêche de faire quoi que ce soit.
- Nous permet de déplacer le contenu facilement. Il nous suffit de faire glisser le nœud d’un sujet d’un emplacement à un autre dans la structure.
- Nous permet de réutiliser de gros blocs de contenu dans plusieurs articles.
- Nous ne publions que rarement des fichiers PDF, mais quand nous le faisons, nous utilisons les fichiers sources DITA.
L’outil DITA que nous utilisons s’appelle Oxygen XML Author. En plus d’un environnement de création de contenu solide, il nous fournit une vaste gamme de fonctionnalités, comme la recherche, la validation et les transformations XHTML. Il existe de nombreux outils de création de contenu DITA, notamment Framemaker, Arbortext et XMetal.
Comment nous créons et publions des articles
Les rédacteurs utilisent Oxygen XML Author pour créer ou modifier le contenu dans les fichiers DITA. DITA ayant été créé pour permettre une publication multicanal à partir d’une source unique, les fichiers texte de la DITA ne contiennent pas de style. Ils ne contiennent que du contenu structuré. Pour le canal Web, la mise en page est fournie par des feuilles de style CSS externes, et non par DITA. Dans notre cas, toute la mise en page est fournie par les feuilles de style de notre thème Guide.
Lorsque nous sommes prêts à publier (généralement au moment de la sortie ou de la mise à jour d’une fonctionnalité du produit), nous utilisons Author pour transformer les fichiers DITA en XHTML qui est une version plus stricte du HTML. Nous publions ensuite les fichiers XHTML dans le centre d’aide à l’aide de l’API du centre d’aide.
À partir de la version 24, Oxygen XML Editor inclut un scénario de transformation intégré qui peut publier des sujets DITA en XHTML et les télécharger directement en tant qu’articles dans un centre d’aide Zendesk. Consultez DITA Map Publishing dans l’aide de XML Editor. Pour une vidéo, voir Publishing Content to Zendesk Help Center dans l’aide de XML Editor.
Il peut arriver que nous devions mettre à jour de nombreux articles dans des délais très courts. Par exemple, lorsque Zendesk a simplifié ses tarifs et sa gestion de la marque, des centaines d’articles modifiés ont dû être publiés avant 8h00, heure du Pacifique, à une date spécifique. Dans les semaines précédant la date limite, les rédacteurs ont mis à jour les fichiers sources DITA, puis nous avons utilisé Author pour transformer les fichiers en masse. Nous avons ensuite publié les fichiers XHTML dans le centre d’aide à l’aide de l’API du centre d’aide. Leur publication n’a demandé que quelques minutes.
Comment nous gérons les fichiers
Nous utilisons GitHub pour gérer nos fichiers DITA. Avant de créer ou de mettre à jour un article, un rédacteur crée une section dans notre référentiel, effectue les modifications, puis crée une demande d’extraction. Cette demande est examinée par les autres rédacteurs de l’équipe. Cela présente l’avantage supplémentaire de donner aux rédacteurs l’occasion de réviser le travail des autres.
Nous stockons les images dans Amazon S3, ou Amazon Simple Storage Service, un service de stockage cloud évolutif fourni par Amazon Web Services (AWS). Toutes les images dans nos articles sont transférées dans votre navigateur à partir du serveur S3, et non du centre d’aide. Le service Amazon S3 simplifie la gestion des images.
Comment nous publions les articles traduits
La langue par défaut de nos centres d’aide est l’anglais. Nous publions également la documentation produits en allemand, espagnol, français, japonais, coréen, portugais brésilien, italien et chinois simplifié.
Quand il est temps de transférer des fichiers pour localisation (traduction), nous utilisons l’API du centre d’aide pour télécharger les fichiers anglais concernés depuis le centre d’aide sous la forme de fichiers HTML. Nous utilisons l’API AWS d’Amazon pour télécharger les images des articles depuis Amazon S3. Nous regroupons les fichiers HTML et les images et les transférons à notre agence de traduction. Quand l’agence nous renvoie les traductions, nous chargeons les articles et les images à l’aide des API du centre d’aide et d’AWS.