SpongeDocs schreiben

Die Sponge Dokumentation, auch SpongeDocs genannt, ist die offizielle Dokumentation des Sponge Projekts. Das Ziel der SpongeDocs ist:

  • Nutzern zu helfen ihren eigenen Sponge basierten Server einzurichten.

  • Entwicklern Informationen bereitzustellen, um an Sponge mitwirken zu können.

  • Entwicklern Informationen bereitzustellen, die beim Entwickeln von Plugins helfen.

Ein Problem melden

Es kann immer mal vorkommen, dass eine Seite nicht mehr aktuell ist, sich ein Fehler eingeschlichen hat oder du dir denkst „das hätte man aber auch besser erklären können!“. Wenn das der Fall ist und du aus irgendeinem Grund nicht in der Lage bist, es selbst zu beheben, kannst du uns auf vier verschiedenen Wegen auf das Problem aufmerksam machen:

  1. Erstelle ein Issue im SpongeDocs Repository auf GitHub

  2. Poste im SpongeDocs Unterforum

  3. Besuche uns im #spongedocs Kanal auf irc.esper.net (du musst dich mit nickserv registrieren)

  4. Besuche uns auf unserem Discord Server im #docs Kanal.

Verfassen der SpongeDocs

Änderungen und Ergänzungen der SpongeDocs sollten als Pull-Request im SpongeDocs Repository auf GitHub <https://github.com/SpongePowered/SpongeDocs>`_ eingereicht werden. Wir verlangen keine perfekten Beiträge, da es üblich ist Pull-Requests zu verfeinern, bevor sie eingepflegt werden. Unvollständige Erklärungen sind ebenfalls willkommen, also habe keine Angst, falls du keinen perfekten Pull-Request liefern kannst. Es wird immer jemand in der Lage sein die Lücken zu füllen.

Die Docs sind in reStructuredText (reST) geschrieben, wenn du mit Markdown (md) vertraut sind, sollte der Schritt zum reST nicht zu schwer sein. Wenn du Probleme damit hast, empfehlen wir dir #spongedocs auf irc.esper.net beizutreten und dort um Hilfe zu fragen, oder trete unserem Discord Server bei und poste im #docs Kanal. Discord und IRC sind verlinkt, so erhältst du die gleiche Unterstützung, unabhängig von der Plattform, die du wählst. Alternativ kannst du auch in unseren forums posten, wenn du denkst, dass es passender ist.

Die Sponge Dokumentation ist lizensiert unter der Creative Commons - Share-Alike license. Kunst Assets werden unter der Creative Commons - Non Commercial, No Derivatives license <https://creativecommons.org/licenses/by-nc-nd/4.0/> gehalten. Beiträge übernehmen diese Lizenz automatisch.

Style-Guide

Um ein konsistentes Aussehen auf allen Seiten der SpongeDocs zu erhalten, sind hier einige Richtlinien zum Schreiben für die Sponge-Dokumentation. Diese Liste kann sich noch verändern, wenn die Docs größer werden.

  1. Überschriften Sollen Am Anfang Großgeschrieben Werden (<- Beispiel) [wenn nicht #8 anwendbar ist].

  2. Seitenüberschriften sollte aussagekräftig (die Überschrift erscheint als Link) sein.

  3. Programmcode sollte in inline literals oder Codeblöcken stehen.

  1. Versuche nicht zu viel Text in Codeblöcke zu setzen, wie sie nicht übersetzt werden können. Versuche so wenige Kommentare wie möglich in Codeblöcke zu schreiben. Einfacher Platzhalter-Text kann in einigen Beispielen erforderlich sein. Im Idealfall werden kurze Codebeispiel-Blöcke genutzt, gefolgt von einer Erklärung für jedes Beispiel im Fließtext. Möglicherweise gibt es natürlich einige Konzepte, die nicht mit einem kurzen Beispiel illustriert werden können.

  2. Verwende die folgenden Code-Block-Typen für bestimmte Code-Block:

  • Groovy/Gradle-Dateien -> groovy

  • Hocon-Config -> guess (hocon Highlighting wird noch nicht unterstützt)

  • In-Game/Server Konsole Kommandos -> none

  • Java-Code -> java

  • Json-Config -> json

  • Linux-Terminal -> bash

  • Logs -> none

  • Text -> text

  • Windows-Konsole -> bat

  1. Trenne Seiten für Benutzer, Plugin- und Sponge-Entwickler.

  2. Vermeide es, wenn möglich, dich zu wiederholen, indem du Seiten miteinander verlinkst.

  3. Verlinke externe Quellen anstatt sie erneut aufzuschreiben.

  1. Es können Ausnahmen von diesen Regeln für die Übersetzung der Seiten nötig sein.

  1. Unterscheide zwischen SpongeForge, SpongeVanilla und der SpongeAPI.

  2. Wenn es in deiner Sprache furchtbar aussieht, erfinde eigene Regeln.

  3. Sponge ist der Name des Projekts und sollte deshalb NICHT übersetzt werden.

  1. In einige Sprachen kann es nötig sein phonetische Übersetzungen zu verwenden.

  1. Automatische Übersetzer (z.B. Google Übersetzer) sind unbedingt zu vermeiden. Diese enthalten oft Fehler, sodass die Übersetzungen sehr wahrscheinlich abgelehnt werden.

  2. Seitentitel und Überschriften sollten Klartext ohne weitere Formatierungen sein.

  3. Codesymbole sollten ihn ihrer ursprünglichen Form verwendet werden und keine zusätzlichen Leerzeichen enthalten (z.B. blockState (ein Feldname) oder BlockState (ein Klassenname), anstatt block state). Diese sollten auch mit doppelten Backticks (z.B. blockState) versehen werden.

  4. Zeilen sollten nicht länger als 120 Zeichen sein.

  5. Imports sollten in Codeblöcken enthalten sein, wenn sie zum ersten Mal auf der betreffenden Seite genutzt werden, danach können sie weggelassen werden.

Bemerkung

Da Sponge auch weiterhin großen Veränderungen unterliegt, ist mit einem Dokumentationsrückstand zu rechnen. Bis zur offiziellen Veröffentlichung von Sponge wird es sehr wahrscheinlich einige Löcher in der Dokumentation geben. Dennoch sind die SpongeDocs ein lebendiges Dokument und unterliegen ständigen Änderungen und Erweiterungen. Sie werden nie perfekt sein, aber soweit wie möglich in Form gebracht werden.

Beiträge, Anregungen und Korrekturen sind immer willkommen.