SpongeDocs schreiben

Warnung

Dieses Dokument bezieht sich auf eine veralte SpongeAPI-Version und wird nicht länger aktiv gepflegt. Während die Code-Beispiele für diese API-Version immer noch funktionieren, die Richtlinien und einige Links haben sich möglicherweise geändert. Bitte gehe stattdessen zur aktuellen Version der Dokumentation.

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

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 Dokumentation ist in reStructuredText (reST) geschrieben, wenn du bereits Markdown kennst, dann ist es nur ein kleiner Schritt zu reST. Wenn du Probleme beim Schreiben hast, dann poste in unserem Forum oder im #SpongeDocs Kanal auf Esper.net und frage dort nach Hilfe.

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.

  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 Translate) sind unbedingt zu meiden. Diese enthalten oft Fehler, sodass die Übersetzung abgelehnt werden muss.

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

  3. Codesymbole sollen in ihrer ursprünglichen Form verwendet werden und keine zusätzlichen Leerzeichen enthalten (z.B. blockState (ein Feldname) oder BlockState (ein Klassenname) statt block state). Im Fließtext sollen sie außerdem mit doppelten Anführungszeichen versehen werden (z.B. blockState).

  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.