Rédaction de la documentation

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

Modifications rapides

La manière la plus simple de modifier le texte de la documentation est d'utiliser les liens situés au bas 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 l'éditeur, où vous pouvez également voir la forme visuelle résultante.

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), puis le coller dans l'éditeur GitHub lorsque vous avez terminé l'édition. Sous la boîte d'édition se trouve un formulaire à soumettre. Assurez-vous de résumer et d'expliquer brièvement la raison de votre modification ici. Une fois soumise, une demande d'extraction sera créée et pourra être éditée ultérieurement.

Comment écrire ?

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

• Lors de la rédaction, commencez par ce qui est simple et général, puis passez à des sujets plus avancés à la fin. Passez à des sujets plus avancés à la fin.
• N'incluez que les informations que l'utilisateur a réellement besoin de connaître sur le sujet.
• Vérifiez que vos informations sont vraies. Testez d'abord le code avant de le donner.
• Soyez concis – réduisez de moitié ce que vous écrivez. Et recommencez.
• Essayez d'expliquer le sujet aussi bien que possible. Par exemple, essayez d'abord d'expliquer le sujet à un collègue.
• Épargnez les surligneurs de toutes sortes, qu'il s'agisse de caractères gras ou d'encadrés tels que .[note].

Gardez ces points à l'esprit tout au long de votre rédaction. Familiarisez-vous également avec la syntaxe. Vous pouvez utiliser un éditeur de prévisualisation pour prévisualiser l'article au fur et à mesure que vous l'écrivez.

Outre les points susmentionnés, respectez également les lignes directrices suivantes :

• L'anglais étant la langue principale, vos modifications doivent être effectuées dans les deux langues. Si l'anglais n'est pas votre point fort, utilisez DeepL Translator et d'autres personnes reliront votre texte.
• Suivez la norme de codage dans les exemples.
• Écrivez les noms des variables, des classes et des méthodes en anglais.
• Les espaces de noms doivent être indiqués dès la première mention.
• Essayez de formater votre code de manière à ce que les barres de défilement ne s'affichent pas.
• Pour la documentation, référez-vous uniquement à la documentation ou à www.

Contribuer à la documentation

Vous devez avoir un compte GitHub pour contribuer à la documentation. Vous pouvez effectuer des modifications simples directement dans son interface.

Cependant, il est plus utile de connaître les bases du travail avec le système de versionnement Git. Si vous n'êtes pas familier avec Git, vous pouvez consulter ce guide rapide : git – the simple guide, ou utiliser l'un des nombreux outils graphiques : GIT – GUI clients.

Commencez à éditer la documentation en créant une branche du dépôt nette/docs et en la clonant sur votre ordinateur. Ensuite, apportez des modifications dans la branche appropriée, validez les modifications, ajoutez-les à votre dépôt GitHub et envoyez une demande d'extraction au dépôt d'origine nette/docs.

Avant chaque demande d'extraction, il est conseillé de lancer Code-Checker pour vérifier qu'il n'y a pas d'espaces supplémentaires dans le texte.

Structure de la documentation

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

Le contenu de chaque branche est divisé en dossiers principaux représentant chaque domaine 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 contenant des images qui peuvent être intégrées dans les pages de la documentation.