Écrire pour SpongeDocs

Avertissement

This documentation refers to an outdated SpongeAPI version and is no longer actively maintained. While the code examples still work for that API version, the policies, guidelines, and some links may have changed. Please refer to the latest version of the documentation for those.

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 trois 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)

É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 êtes familier avec Markdown (md) le passage à reST ne devrait pas être difficile. Si vous avez un problème avec, nous vous conseillons de rejoindre nos forums ou #SpongeDocs sur Esper.net pour demander de l’aide.

La Documentation de Sponge est licensée sous la Creative Commons - Share-Alike license. Les assets d’art sont sous la Creative Commons - Non Commercial, No Derivatives license. Les contributions acceptent implicitement cet agrément.

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.
  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 (par exemple 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é.