Guide de rédaction
Qui peut contribuer à ce wiki?
Tous les détenteurs d'un compte Calcul Canada. Il revient à l'équipe Calcul Canada de fournir une documentation complète et juste, mais nous sommes à l'ère Wikipédia. Si un utilisateur remarque un problème évident comme un lien brisé ou une coquille, il peut bien entendu le corriger. Aussi, un utilisateur qui le souhaite peut rédiger un article en rapport avec un logiciel qu'il connait bien. L'équipe de documentation Calcul Canada révisera les articles affichés par les utilisateurs pour vérifier leur conformité aux présentes directives.
La collaboration au wiki ne se fait pas de façon anonyme. Vous devez vous connecter en utilisant les coordonnées de votre compte Calcul Canada; ceci nous permet de savoir qui a rédigé ou modifié le contenu.
Contenu du wiki
Ce wiki n'est pas l'endroit où afficher l'information qui relève de la responsabilité de la direction de Calcul Canada, particulièrement de la responsabilité de la directrice générale des Affaires extérieures (ci-après la directrice). Ceci inclut toute information pour communication au grand public, aux médias et aux agences de financement. L'information touchant les activités de formation et de rayonnement ne conviennent pas au contenu de ce wiki en rapport avec la documentation technique. Avant de publier une page ou de modifier le contenu du wiki, posez-vous les questions suivantes :
- Cette information est-elle au sujet de la disponibilité d'une grappe ou d'un service? Si c'est le cas, cette grappe ou ce service a-t-il fait l'objet d'une annonce? Autrement, communiquez avec la directrice avant de publier.
- L'information sur un état susceptible de changer à court terme (disponible, hors ligne, en maintenance, etc.) est probablement sous la responsabilité de l'équipe de suivi.
- L'information s'adresse-t-elle aux utilisateurs ou à d'autres membres des équipes techniques de Calcul Canada? Si elle s'adresse à une équipe technique, elle devrait se trouver sur https://ccdb.computecanada.ca/wiki/ plutôt que sur https://docs.computecanada.ca/wiki/.
- Cette information a-t-elle une incidence sur la sécurité de nos systèmes ou des données sur nos systèmes? Si c'est le cas, communiquez avec le directeur de la sécurité de l'information avant de publier.
- L'information s'adresse-t-elle à un utilisateur potentiel plutôt qu'à un détenteur de compte? Il y a ici une zone grise : un utilisateur potentiel pourrait vouloir connaitre les détails techniques en rapport avec nos services et nos sites, tout comme un détenteur de compte. Cependant, si l'information n'est d'intérêt que pour un utilisateur potentiel, elle devrait se retrouver sur https://computecanada.ca plutôt que dans https://docs.computecanada.ca/wiki/.
- Il est approprié de publier des liens externes; voir par exemple Obtenir un compte.
- L'information explique-t-elle comment utiliser une grappe, une application ou un service existants? Si c'est le cas, allez-y.
Style
En cas de doute, imitez les maitres. Trouvez une page que vous aimez et appliquez les mêmes effets de style. Si vous ne trouvez pas sur docs.computecanada.ca, cherchez sur Wikipédia dans son ensemble.
- Isolez le contenu graphique du texte autant que possible. Évitez d'insérer des sauts de ligne pour ajuster l'espacement vertical. N'utilisez pas des espaces ou des tabulations à la fin des phrases. Il est préférable d'utiliser une feuille de styles ou un gabarit.
- Ajoutez des captures d'écran, particulièrement dans les tutoriels et pour expliquer des procédures. Toutefois, une image plein écran placée à même le texte crée un bris dans la structure et le rythme. Placez donc les images à la marge de droite et diminuez leur taille. Si une dimension acceptable ne permet pas de voir certains éléments importants, peut-être serait-il préférable de rogner (to crop) l'image, ou d'inviter le lecteur à "Cliquer pour agrandir".
- Ne variez pas les synonymes. S'ils rendent le texte moins ennuyant, ils créent souvent de la confusion chez les nouveaux utilisateurs ou ceux qui connaissent moins la langue; par exemple, l'emploi sans distinction de machine, hôte, nœud, serveur peut nuire à la compréhension.
- Faites un saut de ligne entre la fin d'une section et le titre de la section suivante : c'est ainsi que la fonction de traduction délimite les unités syntaxiques.
Gabarits
Plusieurs gabarits sont à votre disposition pour une variété d'usages. Deux gabarits particulièrement utiles sont Inclure une commande dans le wiki et Inclure un fichier de code source dans le wiki.