Guide de la documentation de geOrchestra
Qui gère/rédige la documentation?
Le PSC geOrchestra est a l'initiative du livre. Il est destiné à tous et toutes les contributions sont les bienvenues. C'est un projet collaboratif et itératif.
Quelle est la pérennité de la documentation ?
Ce livre à été mis en place lors du Code Sprint geOrchestra du 21 novembre 2017, en partant de la version geOrchestra 16.12. A chaque nouvelle version la documentation est compilée (commentaires/changements...) et versionnée. La documentation de la nouvelle version est remise en place pour être mise à jour et complétée.
Comment réutiliser cette documentation - quels sont les droits ?
Le livre est sous licence CC-BY-SA 4.0 international pour plus de détails sur les droits et les devoirs de cette licences https://creativecommons.org/licenses/by-sa/4.0/
Comment est organisée la documentation?
Le livre geOrchestra est destiné à toutes les informations et documentation sur ce qui est dans le coeur de geOrchestra ce qui est par définition générique a tous les utilisateurs de geOrchestra. La documentation sur les éléments spécifiques (addons, modules, outils annexes) est associée au compte github geOrchestra mais sont dans des livres différents. Tous les livres font référence aux autres livres et documentations annexes via des liens.
Comment participer à l'élaboration de la documentation de geOrchestra?
J'utilise la documentation et il manque des précisions ou je connais une autre façon de faire :
Vous n'avez besoin de rien installer
Vous pouvez ajouter des commentaires dans la documentation existante
Vous devez pour ce faire vous connecter via un compte github/google+/faceboook ou autres
Les administrateurs de la plateforme seront notifiés de vos commentaires
Tous les commentaires sont visibles par tous (pas de besoin de compte pour les voir)
Chaque personne ayant un compte validé par le PSC pourra commenter/commenter un commentaire
Je souhaite rédiger des paragraphes, compléter la documentation existante :
- Vous n'avez besoin de rien installer
- Accédez via un navigateur web à https://www.gitbook.com/book/georchestra/
- Connectez-vous, créer un compte github (ou google+/facebook/ ou dedié)
- Le PSC valide le compte avec les droits associés
- Le même compte vous servira à la fois pour github et gitbook
Quelles sont les demandes de changement?
Lorsque vous travaillez sur un livre, vous allez avoir un tas de changements ou d'idées en cours à tout moment. Certains d'entre eux sont prêts à être publiés, d'autres attendent d'être examinés par vos collaborateurs, d'autres ne sont tout simplement pas prêts. Des demandes de changement existent pour vous aider à gérer cela et à maintenir un flux de travail propre.
Lorsque vous créez une demande de modification dans votre livre, vous créez un environnement dans lequel vous pouvez essayer de nouvelles idées. Les modifications que vous apportez à une demande n'affectent pas la version principale. Vous êtes libre d'expérimenter et de faire des changements, sachant que vos modifications ne seront pas acceptées et fusionnées jusqu'à ce qu'elles soient prêtes à être examinées.
Une fois que vous commencerez à utiliser les demandes de changement, votre flux de travail deviendra plus rapide et plus ciblé. Chaque demande de changement fera un ensemble cohérent et distinct de changements, qui peuvent être examinés indépendamment des autres. Votre version publiée restera toujours polie et cohérente. Et vous aurez une vue d'ensemble de l'évolution de votre livre.
Créer une demande de changement
Tous les collaborateurs disposant d'un accès d'édition peuvent créer une demande de modification depuis l'éditeur GitBook. Dans l'éditeur, cliquez sur Créer une demande de modification .
Vous serez invité à taper un titre et une description pour votre demande de modification afin que les autres sachent sur quoi ils travaillent. Une fois cela fait, vous pouvez le voir dans l'onglet Demande de changement de votre livre sur GitBook.com.
Comme vous pouvez le voir, la demande de changement est vide pour le moment. Vous pouvez maintenant apporter librement des modifications à votre contenu depuis l'éditeur.
Examiner une demande de changement
Pendant que vous travaillez sur votre demande de modification, vous et votre équipe pourrez prévisualiser le résultat, commenter et faire des suggestions, vous aidant ainsi à améliorer la qualité de votre contenu . Tout cela peut être fait à partir de votre page de demande de changement. Les demandes de modification sont conçues pour encourager ce flux de travail.
Accepter les changements
Lorsque la demande de modification est prête, vous pouvez l'accepter et la fusionner dans la vue en ligne. Une fois fusionnées, les modifications seront apportées à la version primaire et seront publiées. Bon travail!
Si vous n'êtes pas satisfait des modifications, vous pouvez également fermer la demande sans la fusionner. La demande de modification peut être rouverte à tout moment sans perte.
Remarque: Si la demande de modification est en conflit avec la version principale, il vous sera demandé de résoudre ces conflits. Cela se produit lorsque des modifications sont apportées au même contenu sur la version principale, pendant que votre demande de modification est ouverte. La résolution des conflits n'acceptera pas la demande de modification , mais elle vous permettra de rester informé des dernières modifications apportées à votre livre. Cette étape peut être prise à tout moment. Le plus tôt le mieux.
Avancé: modifier les demandes et les branches
Chaque livre sur GitBook.com est soutenu par un dépôt Git . Créer une demande de changement, crée une nouvelle branche changes/<id> . Pousser commits à cette branche va ajouter des changements à votre demande. La fusion de cette branche acceptera et fusionnera automatiquement la demande de changement.