Contribuer à la Documentation

La nouvelle documentation devrait s’intégrer correctement avec le reste de la documentation de Elgg.

Tester les documentations localement

Elgg dispose d’un script grunt qui construit automatiquement les docs, les ouvre dans une fenêtre de navigateur, et les recharge automatiquement pendant que vous faites des modifications (le rechargement ne prend que quelques secondes). Vous aurez besoin d’avoir yarn et sphinx installés pour pouvoir utiliser ces scripts.

cd path/to/elgg/
yarn
grunt

C’est aussi simple que cela ! Grunt va continuer à s’exécuter, à vérifier les docs pour des modifications, et à reconstruire automatiquement.

Note

Vous devrez peut-être installer “sphinxcontrib-phpdomain”. Vous pouvez le faire avec la commande suivante : pip install -U sphinxcontrib-phpdomain

Suivez l’organisation du document existant

L’organisation actuelle n’est pas nécessairement La Vraie Manière d’organiser les documentations, mais la cohérence est mieux que l’aléatoire.

intro/*

C’est tout ce que les tout nouveaux utilisateurs ont besoin de savoir (installation, fonctionnalités, licence, etc.)

admin/*

Guides pour les administrateurs. Orienté tâches.

guides/*

Guides de l’API pour les développeurs de plugins. Style recette de cuisine. Exemples solides. Éléments de code solides. Découpé par services (actions, i18n, routage, base de données, etc.). Ceci ne devrait discuter que de l’API publique et de son comportement, pas des détails d’implémentation ou de raisonnement.

design/*

Documentation de conception -design docs- pour les personnes qui veulent avoir une meilleure compréhension de comment/pourquoi le noyau est construit de cette manière. Ceci devrait discuter des détails d’implémentation internes des divers services, de quels compromis ont été faits, et du raisonnement derrière la décision finale. Devrait être utile aux personnes qui veulent contribuer ou pour la communication entre les développeurs du noyau.

contribute/*

Guides des contributeurs pour les diverses manières dont des personnes peuvent participer au sein du projet.

appendix/*

Des informations plus détaillées/méta/de contexte à propos du projet (historique, feuille de route, etc.)

Utilisez « Elgg » d’une manière grammaticalement correcte

Elgg n’est pas un acronyme, l’écrire en majuscules (ELGG ou E-LGG) est incorrect. Veuillez ne pas le faire.

En Français, Elgg ne prend pas d’article quand il est utilisé comme un nom. Voici quelques exemples à imiter :

  • “J’utilise Elgg pour mon site web”

  • “Installez Elgg pour mettre votre communauté en ligne”

Quand il est utilisé comme adjectif, l’article s’applique au nom principal, aussi vous devriez en utiliser un. Par exemple :

  • « Allez sur le site de la communauté Elgg pour trouver de l’aide. »

  • « Hier, j’ai construis un réseau avec Elgg »

Ce conseil peut ne pas être valable pour d’autres langues que l’anglais.

Évitez les pronoms à la première personne

Faites référence au lecteur comme « vous ». Ne vous incluez pas dans la narration habituelle.

Avant :

Quand nous aurons terminé l’installation de Elgg, nous irons rechercher quelques plugins !

Après :

Quand vous aurez terminé l’installation de Elgg, recherchez quelques plugins !

Pour faire référence à vous-même (à éviter si possible), utilisez votre nom et écrivez à la troisième personne. Ceci permet aux futurs lecteurs/éditeurs de savoir de qui les opinions sont exprimées.

Avant :

Je pense que le meilleur moyen pour faire X est d’utiliser Y.

Après :

Evan pense que le meilleur moyen pour faire X est d’utiliser Y.

Éliminer le superflu

Avant :

Si vous souhaitez utiliser une bibliothèque javascript tierce dans le framework Elgg, vous devez prendre soin d’appeler la fonction elgg_register_external_file pour l’enregistrer.

Après :

Pour utiliser une bibliothèque javascript tierce-partie, appelez elgg_register_external_file pour l’enregistrer.

Préférez les dates absolues aux dates relatives

Il est difficile de dire quand une phrase ou un paragraphe particuliers ont été écrits, aussi les dates relatives deviennent vite incompréhensibles. Les dates absolues donnent également au lecteur une bonne indication de si un projet a été abandonné, ou si un conseil est toujours d’actualité.

Avant :

Récemment le truc a été machin. Bientôt, la chose sera machin aussi.

Après :

Récemment (à partir de septembre 2013), le truc a été machin. Il est prévu que la chose soit également machin d’ici octobre 2013.

Ne rappelez pas au lecteur de contribuer

Concentrez-vous pour ne traiter que du sujet en question. Des sollicitations constantes pour du travail gratuit sont agaçantes et donnent l’impression que le projet est dans le besoin. Si des personnes souhaitent contribuer au projet, elles peuvent visiter le guide du contributeur.

Internationaliser la documentation

Quand vous modifiez la documentation, pensez à mettre à jour les modèles de traduction de la documentation avant de faire un commit :

cd docs/
make gettext

Pour plus d’information, voyez https://www.sphinx-doc.org/fr/master/usage/advanced/intl.html#translating-with-sphinx-intl

Points d’attention spécifiques

Quand vous traduisez la documentation soyez conscients de la syntaxe spécifique dans les fichiers de documentation.

NE traduisez PAS

  • Tout ce qui se situe entre des caractères trait vertical ne devrait pas être traduit (par ex., master).

  • Le code, à moins que ce soit un commentaire dans le code.