Règles de base des documentalistes Gentoo

1.  Introduction

Introduction

Le but de l'équipe des documentalistes est de produire une documentation professionnelle qui soit claire, concise et accessible à un utilisateur. Nous avons donc établi des règles et des recommandations qui doivent s'appliquer à tous les documents avant qu'ils ne soient publiés, sur notre site ou ailleurs.

Sujets abordés

Ces règles couvrent ces sujets :

• Organisation de l'équipe de documentalistes ;
• Recommandations aux documentalistes ;
• Recrutement de documentalistes.

2.  Organisation de l'équipe de documentalistes

Organisation

L'équipe est elle-même constituée de petites équipes qui travaillent en étroite collaboration. Chaque petite équipe s'occupe de la documentation d'un sous-projet Gentoo.

Un gestionnaire opérationnel est responsable des tâches quotidiennes au sein du projet de documentation. Il gère l'ensemble des tâches relatives à la documentation à court terme. Le responsable général peut assurer cette gestion s'il le souhaite.

Actuellement, les responsables sont :

Chaque sous-projet a son propre responsable stratégique. Il peut choisir de faire appel à un gestionnaire opérationnel s'il le souhaite. Ses responsabilités sont décrites dans la structure de gestion Gentoo.

Chaque sous-projet l'équipe de documentalistes de Gentoo, ainsi que leurs responsables, sont listés sur la page du projet GDP (Gentoo Documentation Project).

Le responsable stratégique décide de l'ajout de sous-projets.

Membres de l'équipe

Tous les membres doivent être abonnés à la liste de diffusion gentoo-doc@gentoo.org. Elle est utilisée pour discuter de toutes les questions relatives à la documentation. Elle est ouverte à tous, développeurs et autres.

Chaque membre doit faire partie de l'alias docs-team@gentoo.org. Il n'est utilisé que par bugs.gentoo.org pour avertir les développeurs de bogues relatifs à la documentation. Vous pouvez vous ajouter à l'alias en éditant le fichier /var/mail/alias/misc/docs-team sur dev.gentoo.org.

Les membres doivent être disponibles sur le canal IRC #gentoo-doc sur irc.freenode.net quand ils sont connectés.

En fonction de ses tâches et de ses responsabilités, un membre peut disposer d'un accès restreint au server cvs.gentoo.org. L'accès complet au CVS n'est accordé qu'aux développeurs Gentoo. Un serveur CVS anonyme est disponible, il contient les mêmes fichiers que notre serveur CVS principal mais avec quelques minutes de décalage.

Équipes de traducteurs

Chaque langue est prise en charge par une équipe qui est menée par un traducteur responsable, éventuellement aidé d'un second. Ils ont tous deux accès au CVS en écriture. Quand le traducteur responsable n'est pas disponible, son second prend la relève. S'il n'est pas disponible non plus, le ou les mentors prennent les choses en main.

Si un document est traduit dans une langue qui n'est pas supportée officiellement par Gentoo, il sera publié tel quel. Il n'y aura pas de lien vers le document jusqu'à ce qu'une équipe officielle soit mise en place, mais le document sera tout de même accessible sur notre site web et par le CVS.

Si une langue officiellement supportée n'a plus de membres actifs ou si plus personne n'assure la fonction de traducteur responsable, les liens vers les documents seront supprimés, mais les documents resteront disponibles au cas où la langue redeviendrait officiellement supportée.

Pour plus d'information à propos des traductions de documents Gentoo, veuillez consulter le guide du traducteur de documentation Gentoo et la page du sous-projet GDP Internationalisation.

3.  Recommandations aux documentalistes

Légalité

Chaque document doit être publié sous la licence Creative Commons Attribution-ShareAlike License.

Chaque document doit contenir l'élément suivant dans sa source entre les balises </abstract> et <version> :

</abstract>

<!-- The content of this document is licensed under the CC-BY-SA license -->
<!-- See http://creativecommons.org/licenses/by-sa/2.5 -->

<!-- Ce document est publié sous la licence CC-BY-SA -->
<!-- Voyez http://creativecommons.org/licenses/by-sa/2.5 -->
<license/>

<version>...</version>

Bogues et corrections

Chaque bogue rapporté sur bugs.gentoo.org devrait être traité aussi rapidement que possible. S'il ne peut être traité dans un délai raisonnable, la personne qui a rapporté le bogue devrait en être avertie via un commentaire sur le bogue et le bogue devrait être éventuellement enregistré dans le fichier metadoc.xml. Un responsable décidera si le bogue doit être traité prioritairement aux autres tâches.

Quand un membre de l'équipe prend un bogue en charge, il doit se l'assigner et placer docs-team@gentoo.org dans la liste CC. Il ne peut s'attribuer un bogue déjà assigné à un autre membre de l'équipe sans l'accord d'un responsable ou de l'autre membre lui-même.

Développement d'un document

Chaque document peut être développé par les membres de l'équipe de toute manière jugée appropriée, mais le document final doit se conformer à GuideXML et être disponible sur l'infrastructure CVS de Gentoo. Il doit également être enregistré dans le fichier metadoc.xml si besoin.

Quand un nouveau document est commencé ou que des modifications importantes doivent être faites, un bogue doit l'annoncer sur bugs.gentoo.org. Si un tel bogue existe déjà, il n'est pas nécessaire d'en créer un nouveau. Des corrections grammaticales, syntaxiques ou minimes ne requièrent pas qu'un bogue soit créé.

Le numéro de version doit être augmenté et la date ajustée pour toute modification du contenu sauf pour la correction de coquilles dans le texte ou dans les commentaires des exemples de code. Notez que toute modification d'un exemple de code impose une augmentation du numéro de version et une mise à jour de la date.

Les modifications de la présentation de la source XML ne doit générer un nouveau numéro de version et une mise à jour de la date que si la présentation du document s'en trouve aussi modifiée.

La décision d'augmenter le numéro majeur ou mineur dans le numéro de version est laissée à la discrétion du correcteur.

Chaque traduction doit utiliser exactement le même numéro de version et la même date que ceux du document original de façon à garantir une bonne synchronisation entre les différentes traductions.

Relecture et enregistrement

Pour permettre d'intégrer des correctifs rapidement, il est autorisé d'enregistrer des modifications importantes ou d'ordre technique à condition que le correcteur soit certain à 100% que ses modifications sont correctes. Au moindre doute, notamment quand il réagit à une remarque d'un utilisateur, mais qu'il ne peut tester lui-même, le rédacteur doit soumettre sa correction à un développeur Gentoo.

Des modifications importantes ou techniques doivent faire l'objet d'un bogue sur http://bugs.gentoo.org. Le numéro du bogue doit être mentionné lors de l'enregistrement dans le CVS pour permettre un éventuel retour à une version précédente.

Si la correction modifie à la fois le contenu et le style d'écriture de GuideXML, les modifications doivent être enregistrées séparément pour permettre aux traducteurs de visualiser facilement les modifications apportées au contenu.

Dans le cas d'une traduction, le traducteur responsable est chargé de vérifier le document et lui seul (ou son second) peut l'enregistrer dans le CVS sauf s'il est encore en formation, auquel cas c'est le mentor qui doit l'enregistrer.

Sanctions

Il n'y a jamais eu de problème de conduite, mais il est important de noter que les abus commis par des documentalistes Gentoo, notamment :

• induire des utilisateurs ou des développeurs en erreur sciemment,
• rédiger délibérément de la documentation erronée,
• introduire volontairement des erreurs dans les documents,
• outrepasser à dessein les règles d'usage ou les décisions collégiales prises lors de discussions sur nos listes de diffusion,
• rester inactif pendant une longue période sans en avoir informé les responsables et sans donner de réponse aux demandes du responsable opérationnel,

seront signalés aux responsables du projet Gentoo Developer Relations.

4.  Recrutement de documentalistes

Contributeurs, auteurs, traducteurs

Toute personne qui souhaite contribuer à la documentation, corriger des documents existants, en rédiger de nouveaux ou en traduire est encouragée à nous envoyer ses contributions. Qu'elle s'abonne simplement à la liste de diffusion gentoo-doc@gentoo.org après avoir lu et compris ce document.

Procédure de recrutement

Le projet de documentation suit un processus de recrutement strict dont vous pourrez découvrir les détails plus loin. Le processus ne doit être modifié en aucune circonstance. Nous avons choisi ce mode de recrutement pour nous assurer que les recrues sont bien informées de la politique de documentation Gentoo et du style d'écriture appliqué aux documents Gentoo. C'est un processus qui a su montrer ses preuves même si de nombreux contributeurs le voient comme un trop grand fossé à franchir.

Ce processus de recrutement n'a pour objectif que les demandes faites au dépôt de la documentation Gentoo via CVS. Être listé comme mainteneur ou point de contact pour un ou plusieurs documents est attribué par simple requête au chef de projet ou au manager opérationnel.

Étape 1 : Contributions

Aucun processus de recrutement ne commence sans investigations sur les contributions déjà réalisées pour le projet de documentation Gentoo. Le nombre de contributions doit être suffisamment important pour pouvoir assurer une bonne connaissance de GuideXML, du style de code et des politiques en vigueur. La période de contribution doit être étendue pour indiquer le temps passé par le contributeur et montrer la quantité de travail que cela implique.

Le nombre de contributions et la période de contribution dépendent de l'engagement que souhaite solliciter le contributeur. Même s'il est difficile de quantifier cela, la table suivante devrait vous donner un aperçu de la chose. La décision finale n'appartient cependant qu'au manager opérationnel.

Une mise à jour consiste en la modification non triviale d'une quelconque documentation, traduction ou quoi que ce soir d'autre, entièrement écrite par le contributeur et soumis après vérification par un développeur documentaliste. La période est fixe : augmenter les contributions ne diminue pas la période. De même, nous ne faisons pas une moyenne sur les contributions dans le temps pour nous assurer que le contributeur ne donne pas un coup de pédale dans le processus puis qu'il attende sagement que cette phase se finisse.

Si cette phase n'est pas réalisée, nous ne pouvons pas savoir si le contributeur comprend réellement l'investissement nécessaire pour être un développeur documentaliste. La validation de son activité se fait à travers les rapports de bogue sur le bugzilla.

Toute demande d'accès CVS qui n'entraîne pas d'activité liée au développement comme indiqué dans la table ci-dessus ne sera pas prise en considération.

Si vous sentez que vous avez réalisé un nombre suffisant de contributions, contactez le manager opérationnel du projet de documentation Gentoo. Il vous demandera vos coordonnées et toutes les informations nécessaires puis s'occupera de vous faire passer à l'étape suivante.

Étape 2 : Début de la procédure de recrutement

Lors de cette période qui devrait être proche de celle indiquée dans le tableau précédent, les correctifs de la recrue ne seront plus édités par aucun développeur du projet de documentation, mais seront soit soumis tels quels, soit refusés. La recrue se verra également assigner un mentor développeur documentaliste à temps plein qui le guidera lors des dernières étapes.

La qualité des contributions sont ici le point important de l'étape. Tous les correctifs qui ne suivent pas les règles de documentation, de style de code ou tout autre guide affectant le document seront refusés.

Lors de cette période :

• Nous vous conseillons d'apprendre les tâches internes à Gentoo. C'est un apprentissage nécessaire dans la mesure où vous devrez par la suite répondre au Quizz du Personnel.
• Nous vous demanderons de remplir le Quizz du projet de documentation Gentoo. Vous devrez passer avec succès l'intégralité de ce test (répondre à toutes les questions) avant de pouvoir passer à l'étape suivante.

Étape 3 : Recrutement Gentoo

Une fois l'étape 2 finie, le manager opérationnel contactera les Relations entre Développeurs Gentoo et leur donnera le signal final de début du processus de recrutement Gentoo après lequel vous pourrez disposer d'une adresse e-mail Gentoo et serez assigné à un ou plusieurs sous-projets.

Ce document est protégé par la licence Creative Commons : Paternité - Partage des Conditions Initiales à l'Identique 2.5.