Article original : Documentation Libraries to Help You Write Good Docs

Une bonne documentation de projet est la clé du succès pour toute entreprise, startup ou projet individuel. Sans documentation, il est beaucoup plus difficile pour les nouveaux développeurs ou autres d'utiliser votre projet.

Dans cet article, je vais discuter de certaines de mes bibliothèques préférées que vous pouvez utiliser pour construire votre site de documentation.

Et ne vous inquiétez pas si vous n'avez pas encore beaucoup d'expérience dans la création de documentation. Que vous ayez construit un site de documentation simple pour une petite startup ou un projet personnel, ou un site vaste et complexe pour une grande entreprise, ces bibliothèques vous seront utiles.

Conseils pour rédiger une bonne documentation

Avant d'aborder les bibliothèques elles-mêmes, il y a quelques points critiques que vous voudrez garder à l'esprit lorsque vous construisez vos sites de documentation.

Assurez-vous que votre documentation est propre et facilement reconnaissable.

Assurez-vous que votre dossier de documentation est séparé dans le mono dépôt, même si vous utilisez un poly dépôt ou un dépôt séparé.

Ce dépôt séparé ne doit contenir que les fichiers markdown et mdx. Cela aidera vos contributeurs à reconnaître facilement quel dossier est destiné à la documentation.

Un excellent exemple de documentation propre est Next.js, qui a un dossier séparé pour la documentation, comme vous pouvez le voir ci-dessous :

La documentation de Nextjs est facile à reconnaître dans le mono dépôt, et elle ne contient que le markdown. La documentation de Nextjs est facilement reconnaissable dans le mono dépôt et ne contient que le Markdown.

Fournissez des directives claires dans votre documentation.

Pour améliorer la qualité de la documentation, vous devez rédiger des directives claires pour les rédacteurs techniques. Par exemple,

  1. quel front matter est requis dans le fichier markdown ?
  2. Quelles conventions d'orthographe sont correctes – par exemple, acceptez-vous javascript (tout en minuscules) ou JavaScript (avec la casse appropriée) ? Ou les deux ?
  3. Quelles commandes sont nécessaires pour le formatage et le linting avant d'appliquer une pull request ?

Un conseil pro pour les sites de documentation est de mentionner des ressources supplémentaires, telles que des tutoriels, des cours et des liens vers des articles pour les nouveaux contributeurs.

Les meilleurs exemples de directives claires sont Next.js et le Awesome Repository. Les deux ont des directives claires pour la documentation.

Nextjs a des directives claires pour la documentation. Nextjs a des directives claires pour la documentation.

Facilitez la contribution.

Lorsque les contributeurs veulent aider avec votre projet, beaucoup d'entre eux veulent simplement se concentrer sur l'écriture. La plupart des rédacteurs techniques ou des contributeurs de documentation n'ont pas le temps d'installer et de configurer votre projet localement.

De nombreux IDE en ligne sont disponibles ces jours-ci, et d'autres arrivent, tels que GitHub Dev, VS Code Dev, Code Sandbox et GitLab.

De nos jours, de nombreux développeurs et contributeurs mettent à jour le fichier de documentation en utilisant l'IDE intégré de GitHub ou d'autres IDE en ligne et créent des pull requests sans installer votre dépôt localement.

Vous devez donc au moins configurer votre projet pour qu'il fonctionne avec l'un des IDE en ligne. Cela aide à gagner du temps et améliore la productivité du rédacteur technique et du contributeur.

Bibliothèques de documentation utiles :

  1. Nextra
  2. Docusaurus
  3. Lume
  4. Docsify.js
  5. Markdoc
  6. Content layer
  7. Git book
  8. Outstatic CMS
  9. Code doc
  10. Frontmatter

Nextra

Nextra Nextra

Nextra est un framework de génération de site open-source, simple, puissant et flexible construit sur Nextjs. Nextra a été créé par des développeurs chez Vercel.

Nextra aide à gérer votre contenu avec MDX. Avec Nextra, vous pouvez construire des sites web de documentation à petite et grande échelle.

Nextra vient avec diverses fonctionnalités intégrées, telles que :

  1. Organiser le contenu avec le routage du système de fichiers.
  2. Basculer le thème (Thème clair à sombre)
  3. Recherche intégrée
  4. Plusieurs mises en page
  5. Surlignage de syntaxe
  6. Plusieurs langues (Internationalisé)
  7. Thèmes personnalisés

Nextra aide également à gagner du temps et de l'énergie, car vous pouvez travailler directement sur votre documentation sans écrire une seule ligne de code. Vous n'avez pas non plus à maintenir la base de code. Cela vous permet de vous concentrer sur la rédaction de la documentation.

Inconvénients

  1. Il y a moins de personnalisations que vous pouvez faire avec Nextra
  2. Nextra vient avec des fonctionnalités plus limitées

Pour en savoir plus sur Nextra, vous pouvez consulter le tutoriel que j'ai écrit à ce sujet.

Docusaurus

docusaurus docusaurus

Docusaurus est un générateur de site statique open-source construit et maintenu par l'équipe Meta. Docusaurus vous aide à écrire et à gérer vos sites de documentation et de blog, grands et petits.

Docusaurus vient avec diverses fonctionnalités intégrées, telles que :

  1. Il est facile à configurer
  2. Vous pouvez personnaliser la mise en page, le design et les fonctionnalités de votre site avec des composants React
  3. Vous pouvez écrire du contenu en Markdown et MDX.
  4. Il gère bien la localisation
  5. Vous pouvez gérer les versions
  6. Il dispose d'un écosystème de plugins intégré
  7. Vous pouvez personnaliser et changer les thèmes
  8. Il y a un bon support de l'API client
  9. Il dispose d'un support TypeScript et JSDoc
  10. Vous pouvez créer à la fois un blog et un site de documentation avec Docusaurus.

Docusaurus est une bibliothèque bien établie utilisée par de nombreuses entreprises. Et l'un des meilleurs aspects de Docusaurus est qu'il dispose d'un nombre plus important de contributeurs actifs, donc l'outil est bien maintenu.

Inconvénients

  1. Personnaliser et gérer un grand site de documentation avec Docusaurus peut être délicat en raison des options de configuration complexes de Docusaurus.
  2. Configurer les plugins de blog de Docusaurus peut être un énorme casse-tête en raison de la configuration. Enfin, Docusaurus ne peut pas supporter les catégories pour les articles.
  3. Docusaurus ne vient pas avec une fonctionnalité de recherche. Pour activer la fonctionnalité de recherche, vous devez dépendre d'un service tiers. Confirmer la fonctionnalité de recherche tierce n'est parfois pas une tâche facile.

Lume

lume lume

Lume est un générateur de site statique open-source rapide et flexible basé sur Deno. Vous pouvez construire des sites de documentation, un portfolio, un site web d'entreprise ou un blog avec Lume.

Lume vient avec diverses fonctionnalités intégrées, telles que :

  1. Processeurs
  2. Support des plugins
  3. Plusieurs formats de fichiers, comme markdown, yaml, JavaScript, typescript, jsx et nunjucks, et il est facile de l'étendre avec d'autres fonctionnalités.
  4. Support de recherche et de pagination intégré
  5. Il supporte plusieurs moteurs de template (JSX, Preact, MDX, Remark, et ainsi de suite)
  6. Capacité à créer des relations entre deux pages

Vous pouvez personnaliser tant de choses avec Lume que vous ne pourrez peut-être même pas imaginer jusqu'à ce que vous l'essayiez.

Inconvénients

  1. Commencer avec Lume n'est pas une tâche facile. C'est une courbe d'apprentissage plus raide, et il peut prendre un certain temps pour acquérir suffisamment d'expérience pour l'utiliser efficacement – donc Lume n'est pas le meilleur pour les débutants.
  2. Vous avez besoin d'un service tiers pour activer la fonctionnalité de recherche sur votre site web.
  3. Puisqu'il y a tant de personnalisation possible, parfois vous pourriez être confus sur ce que vous avez choisi.

Néanmoins, Lume vous donne plus de contrôle et de puissance sur votre site de documentation, donc si vous êtes prêt à prendre le temps de l'apprendre, je pense que vous l'apprécierez. Vous pouvez lire mon tutoriel approfondi sur freeCodeCamp pour en savoir plus sur Lume.

Docsify.js

Docsify.js Docsify.js

Docsify est un générateur de documentation open-source, simple et léger. C'est un paradis pour les développeurs avec un background en C, Rust et C++. Vous pouvez commencer à utiliser Docsify sans avoir aucune connaissance de JavaScript ou React.js.

Docsify vient avec un certain nombre de fonctionnalités intégrées, telles que :

  1. Il est simple et léger
  2. Il est facile à personnaliser et à configurer
  3. Vous pouvez étendre la fonctionnalité de Docsify avec l'API de plugin intégrée
  4. Il a un support pour plusieurs thèmes
  5. Il y a un support pour les emojis
  6. Il supporte le rendu côté serveur

Avec Docsify, vous pouvez vous concentrer sur la rédaction de la documentation sans vous soucier de la maintenance de la base de code.

Vous pouvez démarrer votre site de documentation en quelques minutes. Vous pouvez déployer le site web Docsify avec un clic sur GitHub pages.

Le plus important avec Docsify est que vous n'avez pas besoin de connaissances préalables pour travailler avec Docsify ou tout autre outil ou configuration.

Inconvénients

  1. Docsify vient avec moins de fonctionnalités, mais des options de personnalisation sont disponibles.
  2. Docsify n'a que quelques thèmes et plugins disponibles sur internet.
  3. La plupart des thèmes que vous trouvez sur internet sont obsolètes en termes d'UI.

Pour en savoir plus sur Docsify, lisez mon tutoriel approfondi sur freeCodeCamp.

Markdoc

Mark doc Mark doc

Markdoc est un framework open-source, puissant et flexible basé sur Markdown. Markdoc est construit et maintenu par l'équipe Stripe. Avec Markdoc, vous pouvez développer vos blogs personnels et sites de documentation.

Markdoc vient avec plusieurs fonctionnalités intégrées, telles que :

  1. Il est léger
  2. Il y a une validation de syntaxe intégrée
  3. Il a un support pour les partials
  4. Vous pouvez étendre Markdoc avec des fonctions personnalisées
  5. Il supporte les tags
  6. Vous pouvez personnaliser les styles avec des annotations
  7. Il supporte les variables et les attributs

Markdoc est convivial pour les développeurs et les rédacteurs. Vous pouvez construire des documentations interactives et des sites de contenu statique en utilisant du HTML pur, Next.js et React.js.

Inconvénients

  1. Pour travailler avec makdoc, vous devez écrire tout le code du site web à partir de zéro.
  2. Markdoc n'est pas pour les développeurs débutants. Vous devez connaître certains concepts avancés de JavaScript et React lorsque vous travaillez avec Markdoc.

Contentlayer

Content layer Content layer

Contentlayer est un SDK de contenu open-source qui valide et transforme votre contenu en données JSON sûres pour que vous puissiez facilement l'utiliser avec vos frameworks existants, tels que Next.js.

Le meilleur aspect de Contentlayer est que vous pouvez construire un schéma sûr pour votre blog et votre documentation.

Contentlayer fonctionne de manière similaire à Markdoc – vous devez écrire la documentation et maintenir la base de code.

Il y a de nombreuses fonctionnalités utiles, mais en voici quelques-unes :

  1. Il est agnostique en termes de framework
  2. Il est construit pour être très rapide
  3. Il facilite l'analyse du contenu sur votre site
  4. Vous pouvez utiliser JavaScript/TypeScript – aucun nouveau langage de requête requis
  5. Il a une validation automatique du contenu et du frontmatter

Inconvénients

  1. Contentlayer vient avec un support pour un nombre limité de frameworks.
  2. Vous devez écrire le code du site web à partir de zéro pour travailler avec Contentlayer.

Lisez mon tutoriel approfondi sur Medium pour en savoir plus sur Contentlayer.

Gitbook

Git book Git book

Gitbook n'est pas open-source, mais il vient avec des plans gratuits et payants. Gitbook est construit et conçu pour gérer la documentation. Vous pouvez même développer votre site de documentation d'API et de service avec Gitbook.

Git Book vient avec diverses fonctionnalités intégrées, telles que :

  1. Il a une solution sans code
  2. Vous pouvez facilement l'intégrer avec d'autres applications
  3. Vous pouvez personnaliser et changer le thème avec un clic
  4. Il est facile à utiliser pour collaborer avec votre équipe
  5. Il a un éditeur puissant basé sur des blocs
  6. Vous pouvez intégrer votre code de démonstration avec l'IDE code sandbox
  7. Il a un support de recherche intégré
  8. Il a un support SEO intégré, sitemap et caching & CDN

Gitbook vient avec une solution sans code – vous n'avez pas besoin d'écrire une seule ligne de code pour créer un site de documentation. Gitbook vous offre une sensation moderne pour créer de la documentation sans écrire de code.

Vous pouvez intégrer Gitbook avec d'autres services comme GitHub. Et vous n'avez pas besoin de vous soucier du déploiement de Gitbook – il fait tout le travail difficile pour vous. Avec un clic, vous pouvez vous concentrer sur l'écriture et la conception ou le changement de thèmes dans votre documentation dans Gitbook.

Inconvénients

  1. De nombreuses fonctionnalités comme la personnalisation du thème et la gestion de l'équipe viennent avec le plan payant.

Outstatic CMS

Outstatic CMS Outstatic CMS

Outstatic CMS est un CMS statique open-source basé sur Next.js qui vous aide à gérer votre contenu avec l'aide de GitHub.

Outstatic cms vient avec plusieurs fonctionnalités intégrées, telles que :

  1. Il y a une option de complétion par IA
  2. Vous pouvez gérer votre contenu avec des champs personnalisés
  3. Il est rapide et facile à configurer
  4. Vous n'avez pas besoin de base de données
  5. C'est un éditeur de contenu moderne

En utilisant Outstatic CMS, vous pouvez facilement publier, mettre à jour et supprimer le contenu en utilisant le tableau de bord et l'éditeur. Cela est utile si vous ne savez pas comment utiliser Markdown et certains qui dépendent des outils de grammaire, par exemple, Grammarly, Turnitin, Quillbot, et ainsi de suite.

Outstatic CMS ne fonctionne qu'avec Next.js et GitHub. Outstatic crée directement du contenu à l'intérieur de votre dépôt GitHub en utilisant l'API Github.

Inconvénients

  1. Vous devez écrire le code de conception du site web pour construire et tester à partir de zéro.
  2. Outstatic CMS ne fonctionne pas hors ligne.

Lisez mon tutoriel approfondi sur Medium pour en savoir plus à ce sujet.

Code doc

Code Doc Code Doc

Code Doc est un outil open-source, simple, léger et facile à configurer pour générer de la documentation qui aide à créer de beaux et modernes sites de documentation logicielle en quelques minutes.

Code Doc vient avec plusieurs fonctionnalités intégrées, telles que :

  1. Il est simple et léger
  2. Il est facile à personnaliser et à configurer
  3. Il a une expérience améliorée de markdown et de bloc de code
  4. Il a une recherche intégrée et un mode sombre
  5. Vous pouvez étendre la fonctionnalité avec l'API de plugin Code doc
  6. Vous pouvez construire vos propres composants personnalisés

Avec code doc, vous vous concentrez sur la rédaction de votre documentation plutôt que sur l'écriture et la maintenance de votre base de code. Mais Code Doc est facile à personnaliser et à configurer. Vous n'avez pas besoin de connaissances préalables pour l'utiliser.

Le plus important avec Code Doc est qu'il a des fonctionnalités d'UI plus modernes que Docsify.

Inconvénients

  1. Un projet ou un dépôt Code Doc ne peut pas être activement maintenu par son développeur.

Front Matter

Front Matter CMS Front Matter CMS

Front Matter est un CMS Headless directement dans votre Visual Studio Code. Front Matter donne un coup de main aux rédacteurs techniques et aux codeurs.

Front Matter cms vient avec plusieurs fonctionnalités intégrées, telles que :

  1. Il fonctionne de manière transparente avec n'importe quel générateur de site statique
  2. Il est entièrement configurable
  3. Il apporte les fonctionnalités/avantages d'un CMS à votre VS Code
  4. Vous obtenez un aperçu complet du site/de la page dans VS Code
  5. Vous pouvez gérer votre contenu, vos médias, vos extraits et vos données avec VS Code
  6. Vous pouvez éditer vos métadonnées
  7. Vous pouvez vérifier votre statut SEO dans VS Code

L'outil fonctionne à l'intérieur de VS Code, vous permettant d'éditer, d'écrire, de mettre à jour et de supprimer de la documentation dans votre VS Code sans jamais avoir à quitter l'éditeur. Vous pouvez écrire votre documentation en utilisant Markdown et VS Code.

Vous pouvez également éditer vos métadonnées (front matter comme le titre, la description, le tag, la date, et ainsi de suite) et vérifier le statut SEO dans VS Code.

Le meilleur aspect est d'intégrer Front Matter avec d'autres outils ou bibliothèques, tels que Nextra, Docusaurus, Lume et Docsify, pour améliorer l'expérience d'écriture des développeurs en utilisant VS Code.

Inconvénients

  1. Vous ne pouvez pas utiliser Front Matter CMS avec d'autres IDE comme Vim, Neovim, Atom, Sublime Text, JetBrains IDEs, et ainsi de suite.
  2. Front Matter CMS n'est pas utile pour tout le monde. Front Matter CMS cible uniquement les développeurs de logiciels qui le trouveront très utile.

Lisez mon tutoriel approfondi sur Medium pour en savoir plus sur le Front Matter CMS.

Conclusion

Sans documentation, votre produit ou service ne sera jamais réussi. Passez autant de temps sur une base de code que sur la documentation.

Pour une documentation rapide et à court terme, je recommande Git Book, Nextra et Docusaurus. Si vous avez du temps et des équipes, optez pour Outstatic CMS, Content Layer et Markdoc. Enfin, si vous ne connaissez pas JavaScript et React.js, vous pouvez opter pour Git Book et Docsify.

Je ne recommande pas la bibliothèque Code Doc en raison de sa maintenance inactive par son développeur. Je ne suis pas sûr que Code Doc ait été abandonné par son développeur ou non.

Vous pouvez m'engager en tant que développeur freelance sur Upwork et autres mises à jour. Suivez-moi sur Twitter (X) et Medium.