Contribuer à la documentation ***************************** .[perex] Contribuer à la documentation est l'une des activités les plus utiles, car elle aide les autres à comprendre le cadre. Comment écrire ? .[#toc-how-to-write] ------------------------------------- La documentation est principalement destinée aux personnes qui découvrent le sujet. Elle doit donc répondre à plusieurs points importants : - Commencer par des sujets simples et généraux. Passer à des sujets plus avancés à la fin - Essayez d'expliquer le sujet aussi clairement que possible. Par exemple, essayez d'abord d'expliquer le sujet à un collègue. - Ne fournissez que les informations que l'utilisateur a réellement besoin de connaître pour un sujet donné. - Assurez-vous que vos informations sont exactes. Testez chaque code - Soyez concis - coupez ce que vous écrivez en deux. Et n'hésitez pas à recommencer - Utilisez la mise en évidence avec parcimonie, qu'il s'agisse de polices en gras ou de cadres tels que `.[note]` - Respectez la [norme de codage |Coding Standard] dans le code Apprenez également la [syntaxe |syntax]. Pour avoir un aperçu de l'article en cours de rédaction, vous pouvez utiliser l'[éditeur de prévisualisation |https://editor.nette.org/]. Mutations linguistiques .[#toc-language-mutations] -------------------------------------------------- L'anglais étant la langue principale, vos modifications doivent être rédigées en anglais. Si l'anglais n'est pas votre fort, utilisez [DeepL Translator |https://www.deepl.com/translator] et d'autres personnes vérifieront votre texte. La traduction dans d'autres langues se fera automatiquement après l'approbation et la mise au point de votre texte. Modifications mineures .[#toc-trivial-edits] -------------------------------------------- Pour contribuer à la documentation, vous devez avoir un compte sur [GitHub |https://github.com]. La manière la plus simple d'apporter une petite modification à la documentation est d'utiliser les liens qui se trouvent à la fin de chaque page : - *Show on GitHub* ouvre la version source de la page sur GitHub. Il suffit ensuite d'appuyer sur le bouton `E` pour commencer à éditer (vous devez être connecté à GitHub). - *Open preview* ouvre un éditeur où vous pouvez immédiatement voir la forme visuelle finale. Comme l'[éditeur de prévisualisation |https://editor.nette.org/] ne permet pas d'enregistrer les modifications directement sur GitHub, vous devez copier le texte source dans le presse-papiers (à l'aide du bouton *Copier dans le presse-papiers*) et le coller ensuite dans l'éditeur sur GitHub. Sous le champ d'édition se trouve un formulaire de soumission. N'oubliez pas de résumer et d'expliquer brièvement la raison de votre modification. Après la soumission, une demande d'extraction (PR) est créée, qui peut être modifiée ultérieurement. Modifications plus importantes .[#toc-larger-edits] --------------------------------------------------- Il est plus approprié de se familiariser avec les bases du travail avec le système de contrôle de version Git plutôt que de se fier uniquement à l'interface GitHub. Si vous n'êtes pas familier avec Git, vous pouvez vous référer à [git - le guide simple |https://rogerdudler.github.io/git-guide/] et envisager d'utiliser l'un des nombreux [clients graphiques |https://git-scm.com/downloads/guis] disponibles. Modifiez la documentation de la manière suivante : 1) sur GitHub, créez une [fourche |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] du dépôt [nette/docs |https://github.com/nette/docs] 2) [clonez |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] ce dépôt sur votre ordinateur 3) ensuite, faites des changements dans la [branche appropriée |#Documentation Structure] 4) vérifiez qu'il n'y a pas d'espaces supplémentaires dans le texte à l'aide de l'outil [Code-Checker |code-checker:] 5) sauvegarder (commit) les changements 6) si vous êtes satisfait des changements, poussez-les sur GitHub vers votre fork 7) à partir de là, soumettez-les au dépôt `nette/docs` en créant une [pull request|https://help.github.com/articles/creating-a-pull-request] (PR). Il est courant de recevoir des commentaires contenant des suggestions. Gardez une trace des changements proposés et incorporez-les. Ajoutez les modifications suggérées en tant que nouveaux commits et renvoyez-les à GitHub. Ne créez jamais une nouvelle demande d'extraction juste pour modifier une demande existante. Structure de la documentation .[#toc-documentation-structure] ------------------------------------------------------------- L'ensemble de la documentation se trouve sur GitHub dans le dépôt [nette/docs |https://github.com/nette/docs]. La version actuelle se trouve dans la branche master, tandis que les versions plus anciennes se trouvent dans des branches telles que `doc-3.x`, `doc-2.x`. Le contenu de chaque branche est divisé en dossiers principaux représentant les différents domaines de la documentation. Par exemple, `application/` correspond à https://doc.nette.org/en/application, `latte/` correspond à https://latte.nette.org, etc. Chacun de ces dossiers contient des sous-dossiers représentant les mutations linguistiques (`cs`, `en`, ...) et éventuellement un sous-dossier `files` contenant des images qui peuvent être insérées dans les pages de la documentation.

Contribuer à la documentation

Contribuer à la documentation est l'une des activités les plus utiles, car elle aide les autres à comprendre le cadre.

Comment écrire ?

La documentation est principalement destinée aux personnes qui découvrent le sujet. Elle doit donc répondre à plusieurs points importants :

Commencer par des sujets simples et généraux. Passer à des sujets plus avancés à la fin
Essayez d'expliquer le sujet aussi clairement que possible. Par exemple, essayez d'abord d'expliquer le sujet à un collègue.
Ne fournissez que les informations que l'utilisateur a réellement besoin de connaître pour un sujet donné.
Assurez-vous que vos informations sont exactes. Testez chaque code
Soyez concis – coupez ce que vous écrivez en deux. Et n'hésitez pas à recommencer
Utilisez la mise en évidence avec parcimonie, qu'il s'agisse de polices en gras ou de cadres tels que .[note]
Respectez la norme de codage dans le code

Apprenez également la syntaxe. Pour avoir un aperçu de l'article en cours de rédaction, vous pouvez utiliser l'éditeur de prévisualisation.

Mutations linguistiques

L'anglais étant la langue principale, vos modifications doivent être rédigées en anglais. Si l'anglais n'est pas votre fort, utilisez DeepL Translator et d'autres personnes vérifieront votre texte.

La traduction dans d'autres langues se fera automatiquement après l'approbation et la mise au point de votre texte.

Modifications mineures

Pour contribuer à la documentation, vous devez avoir un compte sur GitHub.

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

Show on GitHub ouvre la version source de la page sur GitHub. Il suffit ensuite d'appuyer sur le bouton E pour commencer à éditer (vous devez être connecté à GitHub).
Open preview ouvre un éditeur où vous pouvez immédiatement voir la forme visuelle finale.

Comme l'éditeur de prévisualisation ne permet pas d'enregistrer les modifications directement sur GitHub, vous devez copier le texte source dans le presse-papiers (à l'aide du bouton Copier dans le presse-papiers) et le coller ensuite dans l'éditeur sur GitHub. Sous le champ d'édition se trouve un formulaire de soumission. N'oubliez pas de résumer et d'expliquer brièvement la raison de votre modification. Après la soumission, une demande d'extraction (PR) est créée, qui peut être modifiée ultérieurement.

Modifications plus importantes

Il est plus approprié de se familiariser avec les bases du travail avec le système de contrôle de version Git plutôt que de se fier uniquement à l'interface GitHub. Si vous n'êtes pas familier avec Git, vous pouvez vous référer à git – le guide simple et envisager d'utiliser l'un des nombreux clients graphiques disponibles.

Modifiez la documentation de la manière suivante :

sur GitHub, créez une fourche du dépôt nette/docs
clonez ce dépôt sur votre ordinateur
ensuite, faites des changements dans la branche appropriée
vérifiez qu'il n'y a pas d'espaces supplémentaires dans le texte à l'aide de l'outil Code-Checker
sauvegarder (commit) les changements
si vous êtes satisfait des changements, poussez-les sur GitHub vers votre fork
à partir de là, soumettez-les au dépôt nette/docs en créant une pull request (PR).

Il est courant de recevoir des commentaires contenant des suggestions. Gardez une trace des changements proposés et incorporez-les. Ajoutez les modifications suggérées en tant que nouveaux commits et renvoyez-les à GitHub. Ne créez jamais une nouvelle demande d'extraction juste pour modifier une demande existante.

Structure de la documentation

L'ensemble de la documentation se trouve sur GitHub dans le dépôt nette/docs. La version actuelle se trouve dans la branche master, tandis que les versions plus anciennes se trouvent dans des branches telles que doc-3.x, doc-2.x.