SpongeDocs Style Guide


#1

To make sure we have consistent format, here are the guidelines we have tried to keep for writing Sponge Documentation.

  1. Headings Should Be Written in Title Case (<- example)
  2. Page headings should be meaningful (the heading appears as a link)
  3. Program code is contained in quotes or code blocks
    i. Try not to put too much text in - code blocks are not translated
  4. Separate areas for Users, Plugin Devs, and Sponge Devs
  5. Avoid repetition by sharing pages where possible
  6. Link to external resources rather than reproduce them
    i. Some exceptions are made for translation purposes
  7. Make distinction between Sponge (coremod), SpongeVanilla and Sponge API
  8. If it looks awful in your language, invent your own rules
  9. Sponge is the project Title and preferably should NOT be translated.
    i. Some languages may wish to use a phonetic translation as well
  10. Automated translations (eg. Google Translate) are strongly discouraged. These often contain serious errors, and are very likely to be rejected
  11. Page Titles and Headings should use plain text, avoiding literal blocks and other formatting.
  12. References to class names should have no extra spaces (eg. blockstate, not block state) and be formatted as a literal (eg. ``class``)
  13. Lines should have a maximum length of 120 characters.
  14. Imports should be written out in code blocks the first time they are referenced in each article, but not repeated after the first time.

This list may get added to (or bent out of shape) as the Docs get bigger, and is reproduced in Contributing to Spongedocs
I hope this helps our Contributors and Translators.

Contributions, suggestions and corrections are always welcome.


Who Typed The FAQ Like This?
German Docs Translation / Deutsche Sponge-Dokumentation
Portuguese (Brazil) Docs Translation / Documentação do Sponge em português do Brasil
Russian Docs Translation / Русская Документация Sponge
Russian Docs Translation / Русская Документация Sponge
Request docs
#2

#3

You certainly know what you're doing with the docs smiley Good to have this smiley


#4

In german using Title Case will look awful in headings...
So we will make use of rule #8 and stick with german orthography smile


#5

After discussion with some of the docs team, a new Style guideline has been added:

. 9. Sponge is the project Title and preferably should NOT be translated.
. Some languages may wish to use a phonetic translation as well.

Basically, Sponge is the product name - a proper noun. It's like a corporate brand, and should not be translated unless there is no reasonable alternative. For some alphabets, a phonetic translation may be helpful.

The preferred option is to use the word "Sponge" in the English alphabet, the same as it appears in the code. For good or ill, English is embedded in Sponge, Java, and the Internet at large.

As always, constructive discussion is welcome.


#6

One more guideline to add, which has been SpongeDocs policy for some time:

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

Please don't waste your time providing un-reviewed Google translations (or similar). Anyone can do that for themselves, and they would rapidly discover how unreliable it is.


#7

A new guideline has been added regarding import statements.

So when you write a page that contains code snippets make sure that for every class / static method that is used there is exactly one import statement, namely at the beginning of the first code snippet to use that class/method.


#8

Can I see a preview before saving the translation? I want to be sure I didn't make any mistakes in syntax.


#9

nope, i don't think so... You'll have to wait till it's built :frowning:


#10

Okay, thanks! I will check my translations more carefully.


#11

You should be fine as long as your formatting mirrors the one in the original string.