VuePress : la documentation simplifiée

Lorsqu'il s'agit de n'importe quel projet qui nécessite une interaction de l'utilisateur (par exemple, les utilisateurs finaux, les mainteneurs, etc.), il y a un facteur critique qui fait la différence entre le succès et l'échec : une bonne documentation. Cela est vrai quelle que soit la taille de votre projet. Après tout, à moins de fournir une assistance individuelle pour votre projet, la documentation est la première ligne de défense pour les utilisateurs qui tentent de résoudre un problème. Et que cela vous plaise ou non, vous n'entendrez jamais d'utilisateurs abandonner après avoir été incapables de résoudre leur problème en raison d'une documentation inadéquate.

Les défis de la création d'une bonne documentation

Lorsqu'il s'agit de rédiger une bonne documentation, il y a quatre problèmes récurrents que les équipes rencontrent souvent :

1. La documentation est souvent obsolète.
   Bien qu'aucune documentation pour un projet ne puisse être une expérience frustrante, il est sans doute pire d'avoir une documentation obsolète . Après tout, le but de la documentation est de fournir aux utilisateurs un ensemble officiel de connaissances sur lequel ils peuvent compter. Lorsqu'il est obsolète, les utilisateurs perdent leur temps et finissent par perdre confiance dans votre produit.
   
   La principale raison pour laquelle la documentation devient obsolète est que la maintenance de la documentation est distincte des modifications du code . Sans investir beaucoup de temps et d'énergie, cela peut être difficile à résoudre car :
   
   1. La documentation vit généralement dans un service tiers comme Confluence ou un Wiki,
   2. Les développeurs sont généralement plus intéressés par l'écriture de code que par la documentation.
2. Les utilisateurs ne sont pas en mesure de fournir facilement des commentaires.
   Peu importe à quel point vous pensez que votre documentation est bonne, elle n'a finalement aucun sens sans la tester avec de vrais utilisateurs qui peuvent fournir des commentaires. Comme mentionné précédemment, un biais courant lors de l'évaluation de l'efficacité de choses comme la documentation est de ne pas tenir compte des utilisateurs qui n'ont pas pu résoudre leurs problèmes et ont abandonné. Étant donné qu'aucune équipe ne serait jamais en mesure de rendre compte de chaque scénario d'utilisation de votre produit par les utilisateurs, les utilisateurs doivent disposer d'un moyen simple et fiable de donner leur avis.
3. La documentation est souvent écrite par des utilisateurs expérimentés pour des utilisateurs expérimentés.
   Le défaut avec l'utilisation d'outils standard comme les wikis ou les fichiers README est qu'ils ne s'adressent souvent qu'à un ensemble spécifique d'utilisateurs qui ont souvent une connaissance préexistante de la bibliothèque et/ou de la pile technologique. En conséquence, il leur est assez simple de naviguer dans l'espace et de trouver ce dont ils ont besoin. Cependant, les nouveaux utilisateurs n'ont pas ces connaissances préalables et ont donc souvent besoin d'une expérience beaucoup plus immersive pour les engager.
   
   Voici quelques exemples :
   
   • Un site web bien conçu,
   • Capacité de recherche,
   • Navigation latérale guidée,
   • Méta-informations facilement identifiables (c'est-à-dire la date de la dernière mise à jour),
   • Contenu immersif qui s'étend au-delà d'un mur de texte difficile à comprendre facilement.
4. Mauvaise infrastructure qui rend la documentation difficile à maintenir.
   Comme si écrire une bonne documentation que les utilisateurs peuvent comprendre n'était pas assez difficile, la facilité avec laquelle un développeur peut écrire et/ou maintenir une documentation est essentielle à sa viabilité à long terme. Ainsi, pour chaque obstacle supplémentaire que les développeurs doivent surmonter pour écrire et/ou maintenir la documentation, plus il est probable qu'il échouera finalement. Par conséquent, il est essentiel que l'expérience de création et la maintenance de toute documentation soient aussi transparentes et engageantes que possible.

Si seulement il y avait un outil qui pouvait faire toutes ces choses pour nous…

Entrer dans VuePress

Lors de la première audition de VuePress, on pourrait être tenté de deviner qu'il s'agit d'une fusion de Vue.js et WordPress. Au lieu de cela, vous devriez considérer VuePress comme :

Vue.js + presse à imprimer

Car en fin de compte, VuePress est un générateur de site statique !

Certains d'entre vous pourraient penser : « Attendez. Un autre générateur de site statique ? Quel est le problème ? »

Bien qu'il existe un certain nombre d'outils qui sont des générateurs de sites statiques, VuePress se démarque du lot pour une seule raison : sa principale directive est de permettre aux développeurs de créer et de maintenir plus facilement une excellente documentation pour leurs projets.

Pourquoi VuePress est-il si puissant pour créer de la documentation ?

La réponse est simple. Il a été conçu avec un seul objectif en tête : aider les développeurs à créer d'excellents sites de documentation tout en maintenant une expérience de création amusante. Cela signifie qu'il fournit un cadre aux développeurs pour :

• Créer de beaux sites de documentation,
• Venez avec des fonctionnalités pré-construites essentielles à tous les sites de documentation,
• Optimisez l'expérience de création pour la rendre aussi simple que la mise à jour d'un fichier Markdown.

VuePress peut coexister avec votre base de code existante

C'est l'une des principales raisons pour lesquelles je le recommande vivement. Lorsqu'il s'agit de maintenir la documentation, une façon de garantir qu'elle sera obsolète est de rendre difficile pour les développeurs la mise à jour des documents lors de l'écriture du code. Si vous compliquez l'expérience de création en forçant les développeurs à mettre à jour les choses à deux endroits différents, cela entraînera beaucoup de frictions et aboutira souvent à ce que la documentation soit laissée de côté. Cela se voit couramment lorsque les développeurs doivent maintenir un outil tiers comme un wiki, en plus de la base de code elle-même.

Parce qu'il s'agit d'un générateur de site statique, cela signifie qu'il peut vivre exactement dans le même référentiel que votre code.

Comme vous pouvez le voir dans cet exemple de structure d'application Web, votre code vivrait normalement dans le répertoire src , mais vous auriez simplement un répertoire docs pour contenir toute votre documentation. Cela signifie que vous bénéficiez des avantages suivants :

• Toute la documentation est désormais sous contrôle de version ;
• Les demandes d'extraction peuvent désormais contenir à la fois des modifications de documentation et de code ;
• Créer des scripts séparés pour exécuter des instances locales de votre code et de vos documents en même temps ;
• Utilisez des pipelines de build pour déterminer si les déploiements de nouveaux sites de documentation sont synchronisés ou non avec les déploiements de code.

Le thème par défaut est livré avec une configuration standard

Rédiger de la documentation est déjà assez difficile, c'est pourquoi VuePress décharge de nombreuses décisions que l'on doit normalement prendre et dispose d'un tas de paramètres par défaut intégrés pour faciliter votre expérience de création :

• La rédaction de contenu se fait principalement avec Markdown.
  Cela signifie que vous pouvez tirer parti de vos connaissances existantes de la syntaxe Markdown pour styliser et formater votre texte.

• Mise en évidence de la syntaxe du code.
  Si vous construisiez vous-même un site, vous auriez besoin de vous battre avec des bibliothèques de coloration syntaxique des couleurs. Mais vous avez de la chance car vous pouvez ajouter des blocs de code dans VuePress est si facile car tout est prêt à l'emploi sans aucune configuration.

• Avant-propos pour définir les métadonnées au niveau de la page.
  Même si vous créez dans un fichier Markdown, vous pouvez utiliser des informations préliminaires (comme YAML, JSON ou TOML) pour définir les métadonnées de votre page afin de faciliter encore plus la gestion de votre contenu !

 --- title: Document Like a Pro lang: en-US description: Advice for best practices tags: - documentation - best practices ---

• Conteneurs Markdown personnalisés.
  Au cas où vous ne le sauriez pas, Markdown a des extensions pour ajouter des raccourcis encore plus utiles pour créer de beaux composants d'interface utilisateur comme des conteneurs personnalisés. Et comme ils sont si utiles dans la documentation, VuePress l'a déjà configuré pour que vous puissiez l'utiliser dès la sortie de la boîte :

Fonctionnalité de recherche intégrée

Avouons-le. Peu importe le temps que nous passons à écrire une excellente documentation, elle reviendra finalement à être inutile si les utilisateurs ne peuvent pas la trouver. Il existe généralement deux approches pour cela :

1. Attendez que les robots des moteurs de recherche explorent lentement votre site dans l'espoir qu'un jour vos utilisateurs pourront trouver la bonne page sur votre site. Pas une bonne solution.
2. Créez votre propre fonctionnalité de recherche, mais cela peut être difficile à mettre en œuvre pour les sites statiques car aucun code côté serveur ne s'exécute pour créer des index de recherche et effectuer les recherches. Sans oublier que cela prend du temps de développement sur le produit lui-même. Donc ce n'est pas génial non plus.

Heureusement pour nous, VuePress est là pour sauver la situation une fois de plus !

VuePress est livré avec une fonctionnalité de recherche intégrée qui génère son propre "moteur de recherche" - vous avez bien lu. Sans aucune configuration ou configuration de base de données supplémentaire, VuePress est configuré pour récupérer l'intégralité de vos documents afin de générer un moteur de recherche simple qui présentera tous vos h1 et h2 à votre utilisateur.

Maintenant, certains d'entre vous pensent peut-être,

"Et si je veux quelque chose qui fournira une indexation de niveau inférieur pour la recherche?"

Eh bien, VuePress vous couvre également car il est conçu pour s'intégrer facilement à Algolia DocSearch qui peut vous fournir cette fonctionnalité gratuitement si vous répondez à leurs exigences :

La navigation dans la barre latérale est aussi simple que d'activer ou de désactiver la fonctionnalité

Pour tous ceux qui ont déjà été responsables de la gestion du contenu, vous savez à quel point il peut être compliqué de créer une barre latérale contenant des éléments imbriqués, puis de suivre la position du lecteur lors du défilement vers le bas. Alors, pourquoi passer du temps là-dessus alors que vous pourriez écrire de meilleurs documents ? Avec VuePress, la barre latérale est aussi simple que de basculer sur le front-mater d'une page :

Génération automatique de métadonnées importantes souvent ignorées

L'une des choses les plus frustrantes qu'un utilisateur peut rencontrer est une documentation obsolète. Lorsqu'un utilisateur suit les étapes et a du mal à comprendre pourquoi quelque chose ne fonctionne pas, être capable de trouver facilement la dernière date de mise à jour peut être extrêmement utile à la fois pour l'utilisateur et pour les responsables du projet.

Avec une configuration simple, VuePress peut assurer la sortie automatique de la dernière date de mise à jour sur la page afin que vos utilisateurs sachent toujours la dernière fois qu'elle a été mise à jour.

En plus de cela, avec un peu de configuration, VuePress permet également aux utilisateurs de contribuer incroyablement facilement à vos documents en générant automatiquement un lien au bas de chaque page qui permet aux utilisateurs de créer facilement une demande d'extraction vers vos documents.

Rien de plus simple pour vos utilisateurs.

Déploiement sur n'importe quel site d'hébergement statique

Étant donné que VuePress est un générateur de site statique à la base, cela signifie que vous pouvez le déployer sur n'importe quelle plate-forme d'hébergement populaire telle que :

• Netlifier
• Pages GitHub
• Pages GitLab
• Héroku
• À présent

Tout ce que vous avez à faire pour créer le site est d'exécuter vuepress build {{ docsDir }} avec l'emplacement de votre répertoire et vous aurez tout ce dont vous avez besoin pour le déployer en direct sur le Web !

Remarque : Pour des guides plus détaillés sur la façon de procéder, consultez les guides de déploiement officiels pour VuePress.

Tirer parti de Vue dans votre fichier Markdown

Je sais je sais. On peut utiliser Vue.js dans notre Markdown ?! Oui, tu l'as bien lu! Bien que techniquement facultatif, c'est probablement l'un des aspects les plus excitants de VuePress car il vous permet d'améliorer votre contenu Markdown comme vous n'avez jamais pu le faire auparavant.

Définissez les données répétitives en un seul endroit et mettez-les à jour partout avec l'interpolation

Dans l'exemple ci-dessous, vous verrez un bref exemple de la façon dont vous pouvez exploiter les variables locales (comme celles définies dans le frontmatter) ainsi que celles définies globalement (comme le titre du site) :

 --- title: My Page Title author: Ben Hong --- # {{ $page.title }} Welcome to {{ $site.title }}! My name is {{ $page.author }} and I'll be your guide for today!

Utiliser les composants Vue dans Markdown

Je vais vous donner un moment pour vous reprendre après avoir lu ceci, mais oui, les composants Vue en direct avec une instance Vue complète peuvent être à vous si vous le souhaitez ! La configuration demandera un peu plus de travail, mais il faut s'y attendre puisque vous créez du contenu personnalisé qui sera exécuté dans votre documentation.

Voici un exemple rapide de ce à quoi ressemblerait un composant Counter dans un fichier Markdown :

C'est peut-être la partie la plus puissante de la personnalisation disponible pour la documentation, car cela signifie que vous avez maintenant la liberté de créer du contenu personnalisé qui va bien au-delà des capacités du Markdown standard. Qu'il s'agisse de fournir une démo ou un code interactif, les idées sont infinies !

Prochaines étapes

Si vous souhaitez créer un beau site de documentation pour que vos utilisateurs apprennent à utiliser votre produit, rien de plus simple que VuePress. Et même s'il peut être facile de supposer que VuePress ne devrait être utilisé que par des projets qui utilisent Vue.js, cela ne pourrait pas être plus éloigné de la vérité. Voici quelques exemples des différents types de projets utilisant VuePress pour leurs sites de documentation :

• Créer un CMS
• UmiJS (construit pour React)
• openHAB
• paon

En fin de compte, que vous utilisiez VuePress ou non, j'espère que cela vous a aidé à créer une meilleure documentation pour vos utilisateurs.

Autres ressources

Il y a beaucoup de choses intéressantes que je n'ai pas couvertes ici dans cet article (par exemple, les thèmes, les blogs, etc.), mais si vous souhaitez en savoir plus, consultez ces ressources :

• Documents officiels de VuePress
• Une liste organisée de ressources liées à VuePress
• Galerie VuePress
• VuePress Blog Passe-partout