Contribuer à la documentation ***************************** .[perex] Contribuer à la documentation est l'une des activités les plus précieuses, car elle aide les autres à comprendre le framework. Comment écrire ? ---------------- La documentation s'adresse avant tout à des personnes qui découvrent le sujet. Elle doit donc satisfaire plusieurs points importants : - Commencez par des notions simples et générales. Ne passez aux sujets plus avancés qu'à la fin. - Efforcez-vous d'expliquer le sujet le plus clairement possible. Essayez par exemple de l'expliquer d'abord à un collègue. - Ne donnez que les informations dont le lecteur a réellement besoin sur le sujet. - Vérifiez que vos informations sont exactes. Testez chaque bout de code. - Soyez concis : coupez de moitié ce que vous écrivez. Puis recommencez sans hésiter. - Utilisez la mise en valeur avec parcimonie, du texte en gras jusqu'aux encadrés comme `.[note]`. - Respectez le [standard de codage|coding-standard] dans les exemples de code. Apprenez aussi la [syntaxe |syntax]. Pour prévisualiser l'article pendant que vous l'écrivez, vous pouvez utiliser l'[éditeur d'aperçu |https://editor.nette.org/]. Versions linguistiques ---------------------- L'anglais est la langue principale, vos modifications devraient donc idéalement être en anglais. Si l'anglais n'est pas votre fort, utilisez [DeepL Translator |https://www.deepl.com/translator] et d'autres relirons votre texte. La traduction dans les autres langues se fera automatiquement une fois votre modification approuvée et finalisée. Petites modifications --------------------- Pour contribuer à la documentation, vous devez avoir un compte sur [GitHub |https://github.com]. Le moyen le plus simple d'apporter un petit changement à la documentation est d'utiliser les liens en bas de chaque page : - *Afficher sur GitHub* ouvre la version source de la page sur GitHub. Il suffit ensuite d'appuyer sur la touche `E` pour commencer à l'éditer (vous devez être connecté à GitHub). - *Ouvrir l'aperçu* ouvre un éditeur où vous voyez immédiatement le rendu visuel final. Comme l'[éditeur d'aperçu |https://editor.nette.org/] ne sait pas enregistrer directement sur GitHub, une fois vos modifications terminées, vous devez copier le texte source dans le presse-papiers (avec le bouton *Copier dans le presse-papiers*) puis le coller dans l'éditeur de GitHub. Sous le champ d'édition se trouve un formulaire d'envoi. N'y oubliez pas de 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 encore être modifiée. Modifications plus importantes ------------------------------ Plutôt que de vous en remettre à la seule interface de GitHub, mieux vaut connaître les bases du système de gestion de versions Git. Si Git ne vous est pas familier, vous pouvez consulter [git - the simple guide |https://rogerdudler.github.io/git-guide/] et envisager l'un des nombreux [clients graphiques |https://git-scm.com/downloads/guis] disponibles. Modifiez la documentation ainsi : 1) Sur GitHub, créez un [fork |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) Apportez ensuite vos changements dans la [branche appropriée |#Structure de la documentation]. 4) Cherchez les espaces superflus dans le texte à l'aide de l'outil [Code-Checker |tools:code-checker]. 5) Enregistrez (commit) les changements. 6) Si vous êtes satisfait des changements, poussez-les sur GitHub, dans votre fork. 7) 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 avec des suggestions. Suivez les changements proposés et intégrez-les. Ajoutez les changements suggérés sous forme de nouveaux commits et poussez-les de nouveau sur GitHub. Ne créez jamais une nouvelle pull request seulement pour modifier une pull request existante. Structure de la documentation ----------------------------- Toute la documentation se trouve sur GitHub, dans le dépôt [nette/docs |https://github.com/nette/docs]. La version actuelle est dans la branche `master`, les versions plus anciennes dans des branches comme `doc-3.x`, `doc-2.x`. Le contenu de chaque branche est réparti 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 versions linguistiques (`cs`, `en`, ...) et éventuellement un sous-dossier `files` avec les images que les pages de la documentation peuvent inclure.

Contribuer à la documentation

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

Comment écrire ?

La documentation s'adresse avant tout à des personnes qui découvrent le sujet. Elle doit donc satisfaire plusieurs points importants :

Commencez par des notions simples et générales. Ne passez aux sujets plus avancés qu'à la fin.
Efforcez-vous d'expliquer le sujet le plus clairement possible. Essayez par exemple de l'expliquer d'abord à un collègue.
Ne donnez que les informations dont le lecteur a réellement besoin sur le sujet.
Vérifiez que vos informations sont exactes. Testez chaque bout de code.
Soyez concis : coupez de moitié ce que vous écrivez. Puis recommencez sans hésiter.
Utilisez la mise en valeur avec parcimonie, du texte en gras jusqu'aux encadrés comme .[note].
Respectez le standard de codage dans les exemples de code.

Apprenez aussi la syntaxe. Pour prévisualiser l'article pendant que vous l'écrivez, vous pouvez utiliser l'éditeur d'aperçu.

Versions linguistiques

L'anglais est la langue principale, vos modifications devraient donc idéalement être en anglais. Si l'anglais n'est pas votre fort, utilisez DeepL Translator et d'autres relirons votre texte.

La traduction dans les autres langues se fera automatiquement une fois votre modification approuvée et finalisée.

Petites modifications

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

Le moyen le plus simple d'apporter un petit changement à la documentation est d'utiliser les liens en bas de chaque page :

Afficher sur GitHub ouvre la version source de la page sur GitHub. Il suffit ensuite d'appuyer sur la touche E pour commencer à l'éditer (vous devez être connecté à GitHub).
Ouvrir l'aperçu ouvre un éditeur où vous voyez immédiatement le rendu visuel final.

Comme l'éditeur d'aperçu ne sait pas enregistrer directement sur GitHub, une fois vos modifications terminées, vous devez copier le texte source dans le presse-papiers (avec le bouton Copier dans le presse-papiers) puis le coller dans l'éditeur de GitHub. Sous le champ d'édition se trouve un formulaire d'envoi. N'y oubliez pas de 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 encore être modifiée.

Modifications plus importantes

Plutôt que de vous en remettre à la seule interface de GitHub, mieux vaut connaître les bases du système de gestion de versions Git. Si Git ne vous est pas familier, vous pouvez consulter git – the simple guide et envisager l'un des nombreux clients graphiques disponibles.

Modifiez la documentation ainsi :

Sur GitHub, créez un fork du dépôt nette/docs.
Clonez ce dépôt sur votre ordinateur.
Apportez ensuite vos changements dans la branche appropriée.
Cherchez les espaces superflus dans le texte à l'aide de l'outil Code-Checker.
Enregistrez (commit) les changements.
Si vous êtes satisfait des changements, poussez-les sur GitHub, dans votre fork.
De là, soumettez-les au dépôt nette/docs en créant une pull request (PR).

Il est courant de recevoir des commentaires avec des suggestions. Suivez les changements proposés et intégrez-les. Ajoutez les changements suggérés sous forme de nouveaux commits et poussez-les de nouveau sur GitHub. Ne créez jamais une nouvelle pull request seulement pour modifier une pull request existante.

Structure de la documentation

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