Contribuer à la Documentation

La nouvelle documentation devrait s’intégrer correctement avec le reste de la documentation d’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 npm et sphinx installés pour pouvoir utiliser ces scripts.

cd path/to/elgg/
npm install
grunt

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

Suivez l’organisation du document existant

L’organisation actuelle n’est pas nécessairement La Bonne 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. Exemple solide. Elément de code solide. Cassé par les services (actions, i18n, routage, bd, etc.). Ceci devrait discuter seulement de l’API publique et de son comportement, pas des détails d’implémentation ou du 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émentaiton 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 de 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, aussi 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. »

  • « J’ai construis un réseau avec Elgg hier »

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 fini d’installer Elgg, nous allons rechercher quelques plugins !

Après :

Quand vous aurez terminé l’installation d’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.

Supprimer le délayage

Avant :

Si vous souhaitez utiliser une bibliothèque javascript tierce-partie au sein du framework Elgg, vous devriez prendre soin d’appeler la fonction elgg_register_js pour l’enregistrer.

Après :

Pour utiliser une bibliothèque javascript tierce-partie, appelez elgg_register_js 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’informations, voyez http://sphinx-doc.org/latest/intl.html#translating-with-sphinx-intl