Aller au contenu principal

Contribuer à notre documentation

BLOKC prospère grâce aux contributions ouvertes, et notre documentation ne fait pas exception. Que vous soyez développeur, designer ou membre de la communauté, votre contribution aide à rendre nos docs plus utiles et inclusives pour tous. Ce guide vous accompagne dans la configuration de base et les connaissances nécessaires pour commencer à contribuer à la documentation BLOKC hébergée sur GitHub.

Prérequis​

Avant de commencer, assurez-vous d'avoir les outils suivants installés sur votre système :

  1. Git Utilisé pour cloner le dépôt et gérer le contrôle de version. Installer Git

  2. Node.js et npm Nécessaires pour exécuter Docusaurus en local. Installer Node.js (version LTS)

  3. VS Code ou tout éditeur de texte Facilite l'édition des fichiers Markdown et la navigation dans le projet. Télécharger VS Code

  4. Notions de base sur Markdown Notre documentation est rédigée en fichiers .md et .mdx.

Workflow de contribution​

Pour contribuer à la documentation BLOKC, suivez les étapes ci-dessous pour configurer votre environnement local et comprendre la structure du dépôt de documentation.

Pour commencer​

  1. Accéder au dépôt
    Rendez-vous sur le dépôt officiel de la documentation BLOKC sur GitHub.

  2. Forker le dépôt Cliquez sur le bouton "Fork", GitHub créera une copie du repo dans votre compte. (ex : https://github.com/votre-utilisateur/documentation).

  3. Cloner le dépôt
    Utilisez la commande suivante pour cloner le projet sur votre machine locale :

    git clone https://github.com/votre-utilisateur/documentation

  4. Naviguer dans le répertoire du projet

    cd documentation

  5. Installer les dépendances
    Installez tous les paquets requis avec :

    npm install

  6. Lancer la documentation en local
    Démarrez le serveur de développement local avec :

    npm start

Comprendre la structure du projet​

Avant de contribuer, il est utile de comprendre comment la documentation est organisée :

  • Chaque dossier dans le répertoire /docs représente une section majeure de la documentation.
  • Chaque fichier dans ces dossiers est une sous-section ou une page de contenu.
  • Tous les fichiers sont rédigés en Markdown (.md).

Types de contributions​

Vous pouvez contribuer à la documentation de plusieurs façons :

  • Mettre à jour une section ou sous-section existante
    Ajouter de nouvelles informations, corriger des erreurs, mettre à jour du contenu obsolète ou supprimer du contenu non pertinent.

  • Ajouter une nouvelle sous-section
    Créer une nouvelle page de contenu dans une section existante.

  • Créer une nouvelle section
    Introduire une toute nouvelle section à la documentation en ajoutant un nouveau dossier.

Comment contribuer​

1. Mettre à jour une section ou sous-section existante​

  • Identifiez la section ou le fichier à mettre à jour.
  • Ouvrez le fichier .md correspondant.
  • Faites vos modifications directement—ajouts, suppressions ou corrections selon le besoin.

2. Ajouter une nouvelle sous-section​

  • Repérez le dossier de la section concernée.
  • Créez un nouveau fichier avec l'extension .md (ex : nouvelle-sous-section.md).
  • Ajoutez votre contenu au format Markdown.

3. Ajouter une nouvelle section​

  • Créez un nouveau dossier sous le répertoire /docs avec un nom approprié.
  • À l'intérieur de ce dossier, créez un nouveau fichier .md pour votre contenu.
  • Votre nouvelle section et son contenu seront désormais reconnus par le système de documentation.

Soumettre votre contribution​

Une fois vos modifications terminées, suivez ces étapes pour pousser vos changements et ouvrir une Pull Request (PR) :

  1. Créer une nouvelle branche

    git checkout -b votre-nom-de-branche

  2. Stager vos modifications

    git add .

  3. Committer votre travail

    git commit -m "Message descriptif sur votre contribution"

  4. Pousser sur GitHub

    git push -u origin votre-nom-de-branche

  5. Ouvrir une Pull Request
    Rendez-vous sur le dépôt GitHub, comparez les branches et ouvrez une PR pour relecture.

Voir le tutoriel vidéo​

Vous préférez un guide visuel ? Regardez cette courte vidéo qui vous guide à travers tout le processus de contribution—du clonage du dépôt à la soumission de votre première pull request.

Ressources​

  • Docusaurus Docs – Découvrez comment fonctionne Docusaurus, de la configuration à l'écriture de plugins personnalisés.

  • Guide Markdown – Un aperçu rapide de la syntaxe Markdown.

  • GitHub Docs – Guides Git et GitHub pour débutants.