Écrire pour SpongeDocs

La documentation de Sponge, également appelée « SpongeDocs », est la documentation officielle du projet Sponge. Le but de SpongeDocs est de:

  • Aider les utilisateurs a configurer leurs propres serveurs basés sur une implémentation de Sponge.

  • Fournir aux développeurs des informations sur comment contribuer au projet Sponge.

  • Fournir aux développeurs des informations sur comment commencer a développer un plugin.

Signaler les Problèmes

Il est toujours possible qu’une page ne soit pas à jour, qu’une erreur soit bien cachée ou que tout simplement il y ait un meilleur moyen d’expliquer quelque chose. Si c’est le cas et que pour une raison X ou Y vous ne pouvez rien faire, il y a quatre moyens de faire connaître un problème :

  1. Créer un Ticket sur le GitHub de SpongeDocs

  2. Créer un post sur la catégorie SpongeDocs des Forums

  3. Rencontrez-nous sur le channel #spongedocs sur irc.esper.net (vous devez être inscrit)

  4. Rendez-nous visite sur notre serveur Discord, sur le salon #docs.

Écrire la Doc

Tout changements et additions à SpongeDocs doit être soumis en pull request sur le repository SpongeDocs de GitHub.Nous ne demandons pas quelque chose de parfait la première fois et il est courant qu’une requête soit retouchée durant le processus de revue. Les explications incomplètes sont également les bienvenues, ne soyez pas timides si vous ne comprenez pas certaines parties . Il y aura toujours quelqu’un qui pourra combler les lacunes.

Les Docs sont écrites en reStructuredText (reST), si vous êtez familier avec Markdown (md), vous n’aurez pas trop de difficulté avec reST. Si vous avez des problèmes avec, nous vous suggérons de rejoindre le salon #spongedocs sur irc.esper.net et de demander de l’aide ici, ou de rejoindre notre serveur Discord et de poster sur le salon #docs. Discord et IRC sont liés, donc vous aurez le même support indépendamment de la plateforme choisie. Alternativement, vous pouvez poster sur nos forums si vous pensez que c’est plus approprié.

La Documentation de Sponge est sous la licence Creative Commons - Share-Alike license. Les assets d’art sont sous la Creative Commons - Non Commercial, No Derivatives license. Les contributions acceptent implicitement les termes de cette licence.

Guide de Style

Pour être sûr d’avoir un format cohérent sur l’ensemble de SpongeDocs, nous avons écrit ci-dessous des règles d’écriture pour la documentation de Sponge. Cette liste est susceptible de subir des ajouts (ou d’être modifiée) au fur et à mesure que la documentation grossira.

  1. Les Titres Devraient Être en Case de Titre (<- exemple) [sauf si la règle n°8 s’applique].

  2. Les titres de page doivent être significatifs (le titre s’affiche comme un lien).

  3. Le code doit être contenu dans des blocs de code ou dans des inline literals.

  1. Évitez de mettre trop de texte dans les blocs de code, puisqu’ils ne peuvent pas être traduits. Les contributeurs ne devraient pas commenter dans les blocs de code tant que possible. Un simple placeholder peut être nécessaire dans quelques exemples. Idéalement, les exemples dans les blocs de code sont courts, et sont suivis d’un explication pour chaque exemple dans le corps du texte. Bien sûr, il peut y avoir certains concepts qui ne peuvent pas être illustrés avec un exemple court.

  2. Utilisez le type de blocs de code suivant pour les blocs de code particuliers:

  • Groovy/Gradle-Files -> groovy

  • Hocon-Config -> guess (hocon n’est pas encore supporté)

  • In-Game/Server Console Command -> none

  • Java-Code -> java

  • Json-Config -> json

  • Linux-Terminal -> bash

  • Logs -> none

  • Text -> text

  • Windows-Console -> bat

  1. Garder des espaces différents pour les Utilisateurs, les Développeurs de plugin et les Développeurs Sponge.

  2. Éviter les répétitions en partageant les pages lorsque c’est possible.

  3. Fournissez un lien vers une ressource plutôt que de la recopier.

  1. Quelques exceptions sont faites à des fins de traduction.

  1. Distinguer SpongeForge, SpongeVanilla et SpongeAPI.

  2. Si cela semble horrible de votre langue, inventez vos propres règles.

  3. Sponge est le Titre du Projet et NE devrait PAS être traduit.

  1. Il serait préférable, pour certaines langues, d’utiliser une traduction phonétique, ce qui est aussi correct.

  1. Les traductions automatiques (comme Google Translate) sont fortement déconseillées. Souvent, elles contiennent des erreurs graves et sont très souvent rejetées.

  2. Les Titres de page et les En-têtes de Section doivent être en texte brut, c’est à dire avec les blocs littérales et autres mises en forme.

  3. Les références à du code ont des majuscules dans la documentation source et n’ont aucuns espaces (par exemple blockState (un nom de champ) ou BlockState (un nom de classe), plutôt que état du bloc). Ils devraient également être formatés comme un littéral à l’aide de doubles apostrophes inverses (par exemple blockState ) dans le corps du texte.

  4. La longueur maximale des lignes doit être de 120 caractères.

  5. Les importations doivent être écrits dans les blocs de code la première fois qu’ils sont référencés dans chaque article, mais pas les fois d’après.

Note

Comme une Sponge est encore dans un état de flux, un manque de documentation de développement doit être attendu. Jusqu’à la sortie officielle de Sponge, il y a sûrement beaucoup de sujets vides. Néanmoins, SpongeDocs est une documentation évolutive, toujours susceptible d’être modifiée. Elle ne sera jamais parfaite, mais répondra aux besoins aussi bien dans la forme que dans le fond.

Contribuer, suggérer et corriger est toujours apprécié.