SpongeDocs 작성

The Sponge documentation, also referred to as “SpongeDocs”, is the official documentation of the Sponge project. The goal of SpongeDocs is to:

  • 사용자들이 Sponge 로 그들만의 서버를 만들도록 하는 정보를 제공.

  • 개발자들에게 Sponge 프로젝트에 기여하도록 하는 정보를 제공.

  • 개발자들에게 플러그인 개발을 어떻게 시작하는지에 대한 정보를 제공.

Reporting Problems

It may always occur that a page gets outdated, an error sneaks in or you just look at a page and think “Well, there is a better way of explaining this.” If that is the case and you are for some reason not able to provide a fix yourself, there are four ways of making us aware of the problem:

  1. Create an Issue on the SpongeDocs GitHub

  2. Create a Posting on the SpongeDocs Forums Category

  3. Visit us in the #spongedocs channel on irc.esper.net (you need to be registered)

  4. Visit us on our Discord Server, namely the #docs channel.

문서 작성하기

Changes and additions to SpongeDocs should be submitted as a pull request to the SpongeDocs repository on GitHub. We do not require it to be perfect right away as it is common for pull requests to be refined during the review process. Incomplete explanations are also welcome, so don’t shy away if there are some parts you do not understand. There will always be someone able to fill in the gaps.

The Docs are written in reStructuredText (reST), if you’re familiar with Markdown (md) the step to reST shouldn’t be too hard. If you’re having issues with it we suggest that you join our #spongedocs on irc.esper.net and ask for help there, or join our Discord Server and post on the #docs channel. Discord and IRC are linked, so you’ll get the same support irrespective of the platform you choose. Alternatively, you can post on our forums if you think it is more apropriate.

The Sponge Documentation is licensed under the Creative Commons - Share-Alike license. Art assets are held under the related Creative Commons - Non Commercial, No Derivatives license. Contributors implicitly accept this licensing.

스타일 가이드

To make sure we have consistent format across all SpongeDocs pages, here are the guidelines we have developed for writing Sponge Documentation. This list may get added to (or bent out of shape) as the Docs get bigger.

  1. Headings Should Be Written in Title Case (<- example) [unless #8 applies].

  2. Page headings should be meaningful (the heading appears as a link).

  3. Program code should be contained in inline literals or code blocks.

  1. Try not to put too much text in code blocks, as they cannot be translated. Contributors are discouraged from commenting in code blocks wherever possible. Simple place-holder text may be necessary in some examples. Ideally, code block examples will be short, and followed by an explanation for each example in the body text. Of course, there may be some concepts that cannot be illustrated with a short example.

  2. Use the following code block types for particular code blocks:

  • Groovy/Gradle-Files -> groovy

  • Hocon-Config -> guess (hocon highlighting is not yet supported)

  • In-Game/Server Console Command -> none

  • Java-Code -> java

  • Json-Config -> json

  • Linux-Terminal -> bash

  • Logs -> none

  • Text -> text

  • Windows-Console -> bat

  1. Keep separate areas for Users, Plugin Devs, and Sponge Devs.

  2. Avoid repetition by sharing pages where possible.

  3. Link to external resources rather than reproduce them.

  1. Some exceptions are made for translation purposes.

  1. Make distinction between SpongeForge, SpongeVanilla and SpongeAPI.

  2. If it looks awful in your language, invent your own rules.

  3. Sponge is the Project Title and should NOT be translated.

  1. Some languages may wish to use a phonetic translation as well.

  1. Automated translations (e.g. Google Translate) are strongly discouraged. These often contain serious errors, and are very likely to be rejected.

  2. Page Titles and Section Headings should be plain text, avoiding literal blocks and other formatting.

  3. Code symbols should be capitalized in their original form and have no extra spaces (e.g. blockState (a field name) or BlockState (a class name), rather than block state). They should also be formatted as a literal using double backticks (e.g. blockState) in body text.

  4. Lines should have a maximum length of 120 characters.

  5. Imports should be written out in code blocks the first time they are referenced in each article, but not repeated after the first time.

참고

As Sponge is still in a state of flux, a shortfall of development docs is to be expected. Until official release of Sponge, there are sure to be voids in many subjects. Nevertheless, SpongeDocs is a living document, always subject to edit. It’s never going to be perfect, just beaten into shape as needs demand.

Contributions, suggestions and corrections are always welcome.