Escrever os SpongeDocs

Aviso

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.

A documentação do Sponge, também conhecida como «SpongeDocs», é a documentação oficial do projeto Sponge. O objetivo da SpongeDocs é:

  • Ajudar os utilizadores a configurar os seus próprios servidores que usam uma implementação do Sponge.

  • Fornecer aos desenvolvedores informações sobre como contribuir para o projeto Sponge.

  • Fornecer aos desenvolvedores informações sobre como iniciar o desenvolvimento de plugins.

Denunciar problemas

Pode sempre acontecer que uma página fique desatualizada, ou que um erro nos escape, ou simplesmente que ao olhares para uma página sintas «Bem, há uma maneira melhor de explicar isto.» Se se verificar alguma destas hipóteses, e não conseguires, por qualquer razão, fornecer a correção por ti mesmo, há três maneiras de nos fazer saber do problema:

  1. Criar um Issue no GitHub da SpongeDocs

  2. Criar um tópico na categoria SpongeDocs dos Fórums

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

Escrever a Documentação

Mudanças e adições à SpongeDocs devem ser submetidas como um Pull Request no repositório SpongeDocs no GitHub. Não é necessário que esteja perfeito à partida, pois é comum que os Pull Request sejam refinados durante o processo de revisão. Explicações incompletas também são bem-vindas, por isso não te acanhes se há partes que não compreendes. Haverá sempre alguém para preencher essas lacunas.

The Docs are written in reStructuredText (reST), if you’re familiar with Markdown (md) the step to reST shouldn’t be to hard. If you’re having issues with it we suggest that you join our forums or #SpongeDocs on Esper.net and ask for help there.

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. Contributions implicitly accept this licensing.

Style Guide

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.

  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 (eg. 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 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. 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.

Nota

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.