SpongeDocs schrijven

Waarschuwing

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.

De Sponge documentatie, ook wel aangeduid als “SpongeDocs”, is de officiële documentatie voor het Sponge project. Het doel van de SpongeDocs is om:

  • Gebruikers te helpen bij het opzetten van hun eigen servers aangedreven door een Sponge implementatie.

  • Ontwikkelaars te voorzien van informatie over hoe zij kunnen bijdragen aan het Sponge project.

  • Ontwikkelaars te voorzien van informatie over hoe zij kunnen beginnen met het ontwikkelen van een plugin.

Problemen melden

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 three ways of making us aware of the problem:

  1. Creëer een Issue in de repository van SpongeDocs op GitHub

  2. Plaats een post in de SpongeDocs Forums categorie

  3. Bezoek ons in het #spongedocs kanaal op irc.esper.net (u moet geregistreerd zijn)

De Docs schrijven

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.

De Docs zijn geschreven in reStructuredText (reST), mocht u al bekend zijn met Markdown (md), dan zal de overstap naar reST niet moeilijk moeten zijn. Wanneer u er toch problemen mee heeft dan raden wij u aan om onze forums of #SpongeDocs te bezoeken en om hulp te vragen.

De Sponge documentatie is gelicentieerd onder de Creative Commons Naamsvermelding-GelijkDelen licentie. Artistieke bronnen zijn gelicentieerd onder de Creative Commons Naamsvermelding-NietCommercieel-GeenAfgeleideWerken licentie. Bijdrages gaan hiermee automatisch akkoord.

Stijlgids

Om te zorgen dat er een consistent formaat wordt gebruikt op elke SpongeDocs pagina hebben wij enkele richtlijnen voor het schrijven Sponge documentatie opgesteld. Deze lijst kan altijd nog veranderen, zeker wanneer de Docs groter worden.

  1. Koppen Moeten Met Hoofdletters Geschreven Worden (<- voorbeeld) [tenzij #8 van toepassing is].

  2. Paginakoppen moeten zinvol zijn (de kop wordt als een koppeling weergegeven).

  3. Programmacode moet worden opgenomen in inline literals of codeblokken.

  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.

  1. Houd afzonderlijke gebieden open voor gebruikers, plugin ontwikkelaars en Sponge ontwikkelaars.

  2. Vermijd herhaling door waar mogelijk andere pagina’s te vermelden.

  3. Vermeld externe bronnen in plaats van deze te kopiëren.

  1. Enkele uitzonderingen zijn gemaakt voor vertaaldoeleinden.

  1. Maak duidelijk onderscheid tussen SpongeForge, SpongeVanilla en SpongeAPI.

  2. Als het er vreselijk uitziet in uw taal, bedenk dan uw eigen regels.

  3. Sponge is de titel van het project en mag absoluut NIET worden vertaald.

  1. Sommige talen kunnen ook een fonetische vertaling gebruiken.

  1. Geautomatiseerde vertalingen (bijv. Google Translate) worden sterk afgeraden. Deze bevatten vaak ernstige fouten en worden zeer waarschijnlijk afgewezen.

  2. Paginatitels en sectiekoppen moeten platte tekst zijn, waarbij een andere opmaak vermeden moet worden.

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

  4. Regels mogen niet langer zijn dan 120 karakters.

  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.

Notitie

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.

Bijdrages, suggesties en correcties zijn altijd welkom.