-
-
Notifications
You must be signed in to change notification settings - Fork 277
Expand file tree
/
Copy pathdocumentation.texy
More file actions
68 lines (42 loc) · 5.13 KB
/
documentation.texy
File metadata and controls
68 lines (42 loc) · 5.13 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
Comment contribuer à la documentation
*************************************
.[perex]
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 |Coding Standard] dans les exemples de code.
Maîtrisez également la [syntaxe |syntax]. Pour prévisualiser l'article pendant son écriture, vous pouvez utiliser l'[éditeur avec aperçu |https://editor.nette.org/].
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 |https://www.deepl.com/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|https://github.com].
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 |https://editor.nette.org/] 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 |https://rogerdudler.github.io/git-guide/] ou utiliser l'un des nombreux [clients graphiques |https://git-scm.com/downloads/guis].
Modifiez la documentation de cette manière :
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) Ensuite, dans la [branche appropriée |#Structure de la documentation], effectuez les modifications.
4) Vérifiez les espaces superflus dans le texte à l'aide de l'outil [Code-Checker |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|https://help.github.com/articles/creating-a-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 |https://github.com/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.