👀 Read me

👋 Bienvenue sur BookStack !

Avant de continuer, nous te conseillons vivement de lire ces lignes ⬇️

📚 C'est quoi BookStack ?

Cette plateforme est conçue pour centraliser et organiser toute la documentation technique et métier de Yes We Dev, ainsi que pour rassembler les informations pratiques ou les règles de la vie de l'entreprise.

BookStack a une organisation de l'information particulière, inspirée des ... livres : 

• Livres : Les documents sont organisés en "livres", qui peuvent être considérés comme des dossiers de haut niveau ou des catégories.
• Chapitres : À l'intérieur de chaque livre, on retrouve des "chapitres" qui regroupent des pages/thématiques similaires.
• Pages : On trouve enfin les "pages" au plus bas niveau. C'est ici que situe la plupart des informations documentées. 

📝 Type de documentation

Notre mode de documentation est inspiré du framework Diátaxis. Il propose une méthodologie pour organiser la documentation en quatre catégories principales, afin de répondre aux différentes intentions de recherche de l'utilisateur : tutoriel, guide, explication et références

Chez Yes We Dev nous avons opté pour une version simplifié de Diátaxis : nous préconisons l'usage de deux modèles de documentation.

1. Les guides et how-to : pour apprendre en faisant et accompagner dans l'exécution de tâches spécifiques.
2. Les leçons : pour comprendre des concepts, fournir des explications ou informations spécifiques à un sujet.  
   

Pour t'aider à sélectionner le bon format et t'accompagner dans la rédaction d'une doc, des templates sont à dispo :

👉 Template pour écrire un guide / how to

👉 Template pour écrire une leçon

🤝 Redevabilités individuelles

La documentation est un marathon ! Une fois la doc publiée, il faut la maintenir et la faire évoluer pour éviter l'obsolescence. Pour faciliter ce travail, nous avons tous des redevabilités envers Yes We Dev : 

1. Correction proactive : Si je remarque une coquille, une erreur de frappe ou une petite inexactitude dans la documentation, je la corrige immédiatement.
2. Validation de l'exactitude : Si je suspecte qu'une information dans la documentation est incorrecte ou obsolète, je contacte le contributeur original ou un expert du sujet pour clarifier et mettre à jour l'information si nécessaire.
3. Amélioration continue : Si je pense qu'une section de la documentation pourrait être clarifiée ou améliorée, je prends l'initiative d'effectuer des modifications ou d'ajouter des informations supplémentaires.
4. Signalement des manques : Si je ne trouve pas de documentation pour un sujet spécifique, je signale ce manque et, si possible, je contribue à la création de la documentation nécessaire.
5. Feedback constructif : Je fournis des retours sur la documentation existante lorsque j'en ai l'occasion, en suggérant des améliorations, des clarifications ou des ajouts, pour aider à maintenir la qualité et la pertinence de la documentation.
6. Respect des normes : Je m'assure de suivre les normes et les règles de documentation établies lors de la création ou de la modification de la documentation, pour maintenir la cohérence et la lisibilité à travers tous les documents.
7. Partage des connaissances : Je m’efforce de partager mes connaissances et mon expertise en documentant les bonnes pratiques, les astuces et les conseils utiles pour aider mes collègues.