De Confluence à Metalsmith - Histoire de la migration de Nuxeo Docs


Tue 15 November 2016 Par Manon Lumeau

Est-ce que vous avez remarqué l'important changement survenu sur notre site de documentation la semaine dernière ? Si ce n'est pas le cas, arrêtez tout ce que vous êtes en train de faire et allez jeter un œil tout de suite. Ça en vaut la peine !

Après plusieurs mois de dur labeur, nous sommes ravis de vous annoncer le lancement du tout nouveau site de documentation Nuxeo entièrement réorganisé !

AVANT
Old Documentation Site

APRÈS
New Documentation Site

Nous n'avons pas seulement modifié l'apparence du site. Nous avons changé l'outil de documentation lui-même, abandonnant Confluence au profit d'un site Web statique généré avec Metalsmith. Aujourd'hui, nous allons discuter des raisons qui nous ont poussé à migrer l'outil de documentation et des méthodes utilisées pour améliorer l'écosystème de plug-ins Metalsmith.

La génération de site Web statique via Metalsmith, qu'est-ce que c'est ?

Le nouveau site de documentation est un ensemble de textes et de ressources graphiques qui subissent un ensemble de transformations en chaîne afin de générer l'apparence attendue. Metalsmith gère cette logique de pipeline en JavaScript. Il est possible d'ajouter de nouveaux éléments à cette chaîne de commande, par exemple une commande qui remplacera tous les {page page=’my-page’ space=’NXDOC’} par le lien attendu vers une page donnée. Les sources du site Internet sont committées sur GitHub.

Pourquoi nous avons abandonné Confluence et quels sont les avantages de Metalsmith ?

Confluence était un excellent outil lorsque nous avons commencé notre site de documentation. Il était très facile d'utiliser, de créer, de mettre à jour et de maintenir des pages. Mais nous faisons depuis plusieurs mois face à des limitations et nous avons finalement décidé de passer à un autre outil. Voici les raisons qui nous ont poussé à le faire :

  • Meilleur contrôle de l'organisation générale de la doc :
    la priorité a été de simplifier la documentation avec un site plus léger et plus réactif afin d'améliorer la navigation au sein des pages, même si celles-ci ne sont pas dans le même espace ou qu'elles ont des versions différentes. Confluence autorisait la personnalisation, mais dans un format trop propriétaire. La distribution n'était pas simple et la migration entre les versions était réellement fastidieuse.

  • Meilleur contrôle des liens vers les mêmes pages pour les différentes versions du produit :
    une version majeure de Nuxeo Platform est publiée chaque année. Il est possible de parcourir l'ensemble de la documentation pour une version donnée, mais il est également utile de parcourir le contenu associé qui était disponible pour une précédente version de la même page. Et il n'y avait aucun moyen de le faire simplement avec l'ancien site de documentation. Nous sommes désormais capables d'effectuer une mise à jour simple de ces pages en générant automatiquement les liens. Nous avons également la possibilité d'ajouter un lien de retour lorsqu'aucune page pertinente n'est disponible ou si le concept a été modifié.

  • Comportement SEO :
    puisque nous disposons d'un contrôle total du contenu HTML des pages, nous pouvons simplement ajouter les en-têtes nécessaires à la SEO qui sont essentiels pour nous. Ce n'était pas possible auparavant.

  • Meilleure expérience d'édition (support natif du langage Markdown et meilleur contrôle du contenu des pages avec d'excellents éditeurs de contenu) :
    le Markdown peut désormais être utilisé grâce à une extension Confluence, ce qui n'était pas le cas auparavant. La syntaxe type Wiki de Confluence est propriétaire, ce qui pose problème à nos développeurs, qui sont généralement ceux qui rédigent la documentation. Avec les pages en Markdown simplifié, il n'y a plus besoin de basculer vers la "source HTML" ! En plus, Atom.io ou Sublime sont plus intuitifs pour la rédaction de contenu. Le nouveau site est en fait un répertoire de fichiers texte, ce qui nous permet de l'éditer hors ligne, d'effectuer des recherches en masse, de remplacer tous les fichiers en une seule opération, et bien plus.

  • Meilleure gestion des processus et contrôles qualité facilités :
    nous avons commencé à implémenter des éléments de gestion des processus comme la date de révision, le statut de la page, etc. L'ajout de ces contrôles qualité (pour la syntaxe des pages, les liens brisés, etc.) se fait simplement. Plusieurs sont déjà disponibles et nous prévoyons d'en proposer d'autres très prochainement.

  • Le travail collaboratif sous Github est incroyable :
    c'est vraiment plaisant de pouvoir avoir une branche pour chaque modification, pour les pull requests, pour l'historique des commits, etc.

Fonctionnalités ajoutées aux générateurs Metalsmith de base

En lisant la documentation Metalsmith, vous comprendez rapidement que tout est géré par des plug-ins. Nous avons donc listé toutes les fonctionnalités de Confluence que nous souhaitions conserver et nous avons créé des plug-ins pour chacune d'entre-elles. Par exemple :

  • Excerpt
  • Multi-excerpt
  • Tag
  • Historic
  • Page links
  • Left Menu
  • Page Review Warnings
  • Page links

Nous avons également créé de nouveaux plug-ins qui n'étaient pas gérés par Confluence. Par exemple pour le versionage, nous pouvons par exemple lier des pages même si elles ont été renommées entre deux versions. Nous avons également implémenté un processus de révision de la documentation.

Et surtout, ce site de documentation sous Metalsmith nous laisse plus de possibilités pour faire évoluer le contenu, l'organisation, le design graphique et les modes de contribution.

Migration du contenu

Nous avons utilisé l'API Rest de Confluence pour migrer le contenu et appliqué un processus de transformation pour le convertir en Markdown. Nous avons également supprimé les éléments inutiles (y compris les liens courts, le résumé de l'historique, le dernier auteur, les balises, etc.).

Et la suite ?

Ce n'est que le début de notre projet ! Nous travaillons déjà sur la deuxième version du site, qui verra notamment une amélioration de la navigation, des éléments graphiques et du design. Nuxeo est en rapide expansion et la documentation doit pouvoir s'adapter pour répondre à cette rapide évolution.

Nous espérons que ces changements vont vous faciliter la vie, qu'il s'agisse de découvrir Nuxeo, de faire connaissance avec nos produits, de lire plus de documentation ou d'y contribuer. Donnez-nous vos impressions et vos retours sur ce nouveau site !

Enfin, si vous êtes intéressé(e) par l'utilisation des plug-ins Metalsmith que nous publions, GitHub est là pour vous :). Vos retours et suggestions d'amélioration sont toujours les bienvenus ! De nombreuses nouveautés vont arriver donc restez à l'écoute de nos prochaines communications !


Tagged: Documentation, Nuxeo Platform