Documentation Made Easy

Pour tout projet nécessitant une interaction de l'utilisateur (utilisateurs finaux, responsables de la maintenance, etc.). ), il existe 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 personnalisée pour votre projet, la documentation est la première ligne de défense des utilisateurs qui tentent de résoudre un problème. Et que cela vous plaise ou non, vous n'entendrez jamais les utilisateurs abandonner après avoir été incapables de résoudre leur problème en raison d'une documentation insuffisante.

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

Lorsqu'il est question de rédiger une bonne documentation, il Les équipes rencontrent souvent quatre problèmes récurrents:

1. La ​​documentation est souvent obsolète
   Bien qu'aucune documentation relative à un projet ne puisse être une expérience frustrante, il est sans doute pire d'avoir une documentation obsolète . Après tout, l’objet de la documentation est de fournir aux utilisateurs un corpus officiel de connaissances sur lequel ils peuvent compter. Lorsqu'il est obsolète, les utilisateurs perdent leur temps et perdent finalement 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 de code . Sans investir beaucoup de temps et d'énergie, cela peut être difficile à résoudre pour les raisons suivantes:

   1. La documentation réside généralement dans un service tiers, tel que 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.
   Quelle que soit la qualité de votre documentation, votre documentation est finalement dépourvue de sens si vous ne la testez pas avec de vrais utilisateurs pouvant fournir une rétroaction. Comme mentionné précédemment, un biais commun lors de l'évaluation de l'efficacité d'éléments tels que la documentation consiste à ne pas rendre compte des utilisateurs qui étaient incapables de résoudre leurs problèmes et qui ont abandonné. Etant donné qu'aucune équipe ne serait jamais en mesure de rendre compte de chaque scénario d'utilisation du produit par les utilisateurs, ceux-ci doivent disposer d'un moyen simple et fiable pour formuler des commentaires.
3. La documentation est souvent écrite par des utilisateurs privilégiés.
   La faille avec l'utilisation d'outils standard tels que les wikis ou les fichiers README est qu'ils ne s'adressent souvent qu'à un ensemble spécifique d'utilisateurs ayant 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 cette connaissance préalable et ont donc souvent besoin d'une expérience beaucoup plus immersive pour les impliquer.

   Exemples:

   • Un site Web bien conçu,
   • Fonction de recherche,
   • Navigation latérale guidée ,
   • Meta information facilement identifiable (ie, dernière mise à jour),
   • Contenu immersif dépassant un mur de texte difficile à comprendre.
4. Mauvaise infrastructure qui rend la documentation difficile à maintenir.
   Comme si rédiger une bonne documentation que les utilisateurs peuvent comprendre n'est 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 auquel les développeurs doivent faire face pour écrire et / ou maintenir la documentation, plus il est probable qu’elle finira par échouer. En conséquence, il est essentiel que l'expérience de création et la maintenance de toute documentation soient aussi homogènes et engageantes que possible.

S'il ne restait qu'un outil capable de faire tout cela pour nous…

Enter VuePress [19659002] Lors de la première lecture de VuePress, on pourrait être tenté de deviner qu’il s’agit d’un amalgame de Vue.js et de WordPress. Voyez plutôt VuePress comme:

Vue.js + Printing Press

Parce qu’en fin de compte, VuePress est un générateur de site statique!

Certains d’entre vous pensent peut-être: «Attendez. Un autre générateur de site statique? Quel est le problème? ”

Alors qu'il existe un certain nombre d'outils générateurs de sites statiques, VuePress se distingue du groupe pour une raison unique: sa directive principale est de permettre aux développeurs de créer et de gérer facilement une documentation de qualité. 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 des sites de documentation de qualité tout en maintenant une expérience de création amusante. Cela signifie qu'il fournit un cadre permettant aux développeurs de:

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

VuePress peut coexister avec votre base de code existante

C'est l'une des principales raisons pour lesquelles je le recommande vivement. En ce qui concerne la maintenance de la documentation, un moyen de garantir qu’elle sera périmée est d’empêcher les développeurs de mettre à jour la documentation lors de la rédaction de code. Si vous rendez l'expérience de création difficile en obligeant les développeurs à mettre à jour des éléments à deux endroits différents, cela provoquera beaucoup de frictions et conduira souvent à un abandon de la documentation. Cela se produit généralement lorsque les développeurs doivent maintenir un outil tiers, tel qu'un wiki, en plus du code base lui-même.

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

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

• Toute la documentation est maintenant contrôlée par la version;
• Les requêtes d'extraction peuvent désormais contenir à la fois de la documentation et des modifications de code;
• Création de scripts distincts pour l'exécution d'instances locales de votre code et de vos documents en même temps
• Utilisez des pipelines de construction 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 la configuration standard

L'écriture de documentation est assez difficile en soi, donc VuePress déloge une La plupart des décisions que vous devez normalement prendre et qui comportent de nombreux défauts intégrés facilitant votre expérience de création sont les suivantes:

• La rédaction du contenu s'effectue principalement avec Markdown.
  Cela signifie que vous pouvez connaissances existantes de la syntaxe de Markdown pour styler et mettre en forme votre texte.

• Mise en surbrillance de la syntaxe du code
  Si vous construisiez un site vous-même, vous auriez besoin de vous battre avec des bibliothèques de mise en surbrillance de la couleur. Mais vous avez de la chance car vous pouvez ajouter des blocs de code dans VuePress, c'est très simple, car tout est prêt à fonctionner avec une configuration zéro.

• Matière première pour la définition de métadonnées au niveau de la page.
  Même si vous créez un fichier Markdown, vous pouvez utiliser une matière première (comme YAML, JSON ou TOML) pour définir les métadonnées de votre page afin de faciliter la gestion de votre contenu!

 ---
titre: Document Like a Pro
lang: en-US
description: Conseils pour les meilleures pratiques
Mots clés:
  - Documentation
  - les meilleures pratiques
---

• Conteneurs Custom Markdown
  Au cas où vous ne le sauriez pas, Markdown propose des extensions permettant d’ajouter des raccourcis plus utiles pour créer de superbes composants d’interface utilisateur tels que des conteneurs personnalisés. Et comme ils sont très utiles dans la documentation, VuePress l’a déjà configurée pour que vous puissiez l’utiliser immédiatement:

Fonctionnalité de recherche intégrée

Let's face it. Peu importe le temps que nous passons à rédiger une bonne documentation, cela finira par être inutile si les utilisateurs ne peuvent pas la trouver. Il existe généralement deux approches:

1. Attendez que les robots des moteurs de recherche explorent lentement votre site, dans l’espoir que vos utilisateurs trouveront un jour la bonne page sur votre site. Pas une bonne solution.
2. Créez votre propre fonctionnalité de recherche, mais cela peut être difficile à implémenter pour les sites statiques car aucun code côté serveur n’exécute pour créer des index de recherche et effectuer des recherches. Sans compter que cela prend du temps de développement au produit lui-même. Donc, ce n'est pas terrible non plus.

Heureusement pour nous, VuePress est là pour sauver encore une fois le temps!

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 supprimer votre documentation entière afin de générer un moteur de recherche simple qui affichera tous vos fichiers h1 et h2 sur votre utilisateur.

Grand aperçu )

Certains d'entre vous pensent peut-être,

«Et si je veux quelque chose qui fournira une indexation de bas niveau pour search? ”

Eh bien, VuePress vous y a couvert, 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 barre de navigation est aussi simple que d'activer ou de désactiver la fonction

Pour tous ceux qui l'ont déjà été responsable de la gestion g contenu, vous savez à quel point il peut être compliqué de créer une barre latérale comportant des éléments imbriqués, puis de suivre la position du lecteur lors du défilement. 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 texte d'une page:

Génération automatique d'importantes métadonnées souvent négligées

L'un des problèmes les plus frustrants qu'un utilisateur puisse rencontrer est la documentation obsolète. Lorsqu'un utilisateur suit les étapes et ne comprend pas pourquoi quelque chose ne fonctionne pas, il est extrêmement utile de trouver facilement la dernière date mise à jour pour l'utilisateur et les responsables du projet.

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

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

Cela n’est pas si facile pour vos utilisateurs.

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

Depuis VuePress est un générateur de site statique, ce qui signifie que vous pouvez le déployer sur n'importe quelle plate-forme d'hébergement populaire, telle que:

• Netlify
• GitHub Pages
• GitLab Pages
• Heroku
• Now

Tout ce que vous devez faire pour construire le site est exécuté 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!

Note : Pour plus de précisions sur la procédure à suivre, consultez les guides de déploiement officiels de VuePress .

Tirer parti de Vue Inside Your File (Markdown)

]Je sais je sais. Nous pouvons utiliser Vue.js dans notre Markdown?! Oui, tu l'as bien lu! Bien que facultatif sur le plan technique, il s’agit probablement de l’un des aspects les plus intéressants de VuePress car il vous permet d’améliorer votre contenu Markdown comme vous ne l’aviez jamais pu faire auparavant.

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

Dans l'exemple ci-dessous, vous verrez un bref exemple de la manière dont vous pouvez exploiter des variables locales (telles que celles définies dans le tableau avant) ainsi que celles définies globalement (comme le titre du site):

 - -
titre: titre de ma page
auteur: Ben Hong
---

# {{$ page.title}}

Bienvenue à {{$ site.title}}! Mon nom est {{$ page.author}} et je serai votre guide pour aujourd'hui!

Utiliser les composants Vue dans Markdown

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

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

C’est peut-être la partie la plus puissante de la personnalisation disponible pour la documentation depuis cela signifie que vous avez maintenant la liberté de créer du contenu personnalisé qui dépasse de loin les capacités de Markdown standard. Ainsi, qu’il s’agisse de fournir une démonstration ou un code interactif, les idées sont infinies!

Étapes suivantes

Si vous souhaitez configurer un beau site de documentation pour que vos utilisateurs puissent apprendre à utiliser votre produit, devenir beaucoup plus facile que VuePress. Et même s’il est facile de supposer que VuePress ne doit être utilisé que par des projets utilisant Vue.js, cela ne peut être plus éloigné de la vérité. Voici quelques exemples des différents types de projets utilisant VuePress pour leurs sites de documentation:

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

Ressources supplémentaires

Il existe de nombreuses choses intéressantes que je n'ai pas abordées ici dans cet article (par exemple, la thématisation, les blogs, etc.), mais si vous souhaitez en savoir plus, consultez ces ressources:

(dm, yk, il)