Comment contribuer à la documentation

Contribuer à la documentation est l'une des activités les plus enrichissantes, car vous aidez les autres à comprendre le framework.

Comment écrire ?

La documentation est principalement destinée aux personnes qui découvrent le sujet. Par conséquent, elle doit respecter plusieurs points importants :

• Commencez par le simple et le général. N'abordez les sujets plus avancés qu'à la fin.
• Essayez d'expliquer les choses le mieux possible. Essayez par exemple d'expliquer d'abord le sujet à un collègue.
• Ne fournissez que les informations dont l'utilisateur a réellement besoin sur le sujet donné.
• Vérifiez que vos informations sont réellement exactes. Testez chaque exemple de code.
• Soyez concis – réduisez de moitié ce que vous écrivez. Et puis n'hésitez pas à le refaire.
• Économisez toutes sortes de mises en évidence, du texte en gras aux cadres comme .[note].
• Respectez le Standard de codage dans les exemples de code.

Maîtrisez également la syntaxe. Pour prévisualiser l'article pendant son écriture, vous pouvez utiliser l'éditeur avec aperçu.

Versions linguistiques

La langue principale est l'anglais. Vos modifications devraient donc idéalement être apportées aux versions anglaise et tchèque de la documentation. Si l'anglais n'est pas votre point fort, utilisez DeepL Translator et les autres vérifieront votre texte.

La traduction dans les autres langues sera effectuée automatiquement après approbation et finalisation de votre modification.

Modifications triviales

Pour contribuer à la documentation, il est nécessaire d'avoir un compte sur GitHub.

La manière la plus simple d'apporter une petite modification à la documentation est d'utiliser les liens à la fin de chaque page :

• Afficher sur GitHub ouvre la version source de la page donnée sur GitHub. Ensuite, il suffit d'appuyer sur le bouton E pour commencer à éditer (il faut être connecté à GitHub).
• Ouvrir l'aperçu ouvre l'éditeur, où vous voyez directement le rendu visuel final.

Comme l'éditeur avec aperçu n'a pas la possibilité d'enregistrer les modifications directement sur GitHub, il est nécessaire, après avoir terminé les modifications, de copier le texte source dans le presse-papiers (bouton Copy to clipboard) puis de le coller dans l'éditeur sur GitHub. Sous le champ d'édition se trouve un formulaire d'envoi. N'oubliez pas d'y résumer brièvement et d'expliquer la raison de votre modification. Après l'envoi, une pull request (PR) est créée, qui peut être éditée ultérieurement.

Modifications plus importantes

Plutôt que d'utiliser l'interface GitHub, il est préférable d'être familiarisé avec les bases du travail avec le système de contrôle de version Git. Si vous ne maîtrisez pas Git, vous pouvez consulter le guide git – le guide simple ou utiliser l'un des nombreux clients graphiques.

Modifiez la documentation de cette manière :

1. Sur GitHub, créez un fork du dépôt nette/docs.
2. Clonez ce dépôt sur votre ordinateur.
3. Ensuite, dans la branche appropriée, effectuez les modifications.
4. Vérifiez les espaces superflus dans le texte à l'aide de l'outil Code-Checker.
5. Enregistrez (commitez) les changements.
6. Si vous êtes satisfait des changements, envoyez-les (pushez) sur GitHub vers votre fork.
7. De là, envoyez-les au dépôt nette/docs en créant une pull request (PR).

Il est courant que vous receviez des commentaires avec des remarques. Suivez les modifications suggérées et intégrez-les. Ajoutez les modifications suggérées comme de nouveaux commits et renvoyez-les sur GitHub. Ne créez jamais une nouvelle pull request pour modifier une pull request existante.

Structure de la documentation

Toute la documentation est hébergée sur GitHub dans le dépôt nette/docs. La version actuelle est dans la branche master, les versions plus anciennes sont situées dans des branches comme doc-3.x, doc-2.x.

Le contenu de chaque branche est divisé en dossiers principaux représentant les différentes sections de la documentation. Par exemple, application/ correspond à https://doc.nette.org/fr/application, latte/ correspond à https://latte.nette.org, etc. Chacun de ces dossiers contient des sous-dossiers représentant les versions linguistiques (cs, en, fr, …) et éventuellement un sous-dossier files avec des images, qui peuvent être insérées dans les pages de la documentation.