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 (Document Information Typing Architecture) est un modèle de données basé sur XML pour la création et la publication de contenu.
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. 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 et la comparaison de fichiers, le suivi des modifications et les transformations HTML. Il existe de nombreux outils de création de contenu DITA, notamment Framemaker, Arbortext et XMetal.
Comment nous publions dans le centre d’aide
Nous utilisons Author pour créer ou mettre à jour le contenu dans des fichiers sources DITA. Quand nous sommes prêts à passer à la publication (souvent au lancement ou à la mise à jour d’une fonctionnalité produit), nous transformons le contenu DITA en HTML, puis collons manuellement le HTML source dans l’éditeur de code d’article de Guide. Ce n’est pas le processus le plus élégant, mais il a l’avantage d’être simple.
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 8 heures, heure du Pacifique, à une date spécifique. Les semaines précédant ce changement, les auteurs ont mis à jour les fichiers sources DITA, puis nous avons effectué une transformation en masse de tous ces fichiers et les avons transférés dans le centre d’aide à l’aide de l’API Zendesk. Leur publication n’a demandé que quelques minutes.
L’outil de publication en masse que nous utilisons est un outil open source, à la disposition de tous sur GitHub. Rendez-vous sur https://github.com/chucknado/zpu. Pour savoir comment l’utiliser, consultez le fichier lisez-moi sur https://github.com/chucknado/zpu/blob/master/README.md.
Comment nous gérons les fichiers
Nous stockons les fichiers DITA sur un disque Google Team Drive, qui synchronise automatiquement les fichiers avec l’ordinateur de chaque auteur. Ainsi, les auteurs disposent toujours des versions les plus récentes. Quand un auteur enregistre ses modifications d’un article, ces modifications sont immédiatement propagées aux ordinateurs des autres auteurs grâce à la synchronisation Team Drive. Team Drive conserve également toutes les modifications effectuées au cours des 30 derniers jours. Là aussi, l’objectif est d’assurer la simplicité du processus.
Nous stockons aussi des images sur le disque Google Team Drive, mais nous les chargeons sur un serveur de fichiers Amazon S3 pour les mettre à la disposition de tous. Toutes les images dans nos articles sont téléchargé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 aussi la documentation produits en français, allemand, espagnol, japonais, coréen et portugais brésilien.
Quand il est temps de transférer des fichiers pour localisation, nous utilisons l’API du centre d’aide pour télécharger les fichiers anglais concernés depuis les centres d’aide sous la forme de fichiers HTML. Nous utilisons l’API Amazon pour télécharger les images des articles depuis Amazon S3. Nous regroupons les fichiers 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 Amazon.
Le client API que nous utilisons pour gérer les transferts de fichiers s’appelle ZLO (Zendesk Localization Tools ou outils de localisation Zendesk) et a été créé par l’équipe Zendesk chargée de la documentation. Le client ZLO est un outil open source, disponible sur GitHub à https://github.com/chucknado/zlo. Pour en savoir plus au sujet du client ZLO, consultez la documentation sur GitHub.
0 Commentaires
Vous devez vous connecter pour laisser un commentaire.