Escritura de los Spongedocs

La documentación «sponge» o esponja, también conocida como «SpongeDocs», es la documentación oficial del proyecto esponja. La finalidad de los SpongeDocs es:

  • Ayudar a los usuarios a configurar sus propios servidores impulsados una implementación Sponge.
  • Proveer a los desarrolladores con información sobre cómo contribuir al proyecto Sponge.
  • Proveer a los desarrolladores con información sobre como iniciar el desarrollo de la conexion.

Reporte de problemas

Algunas veces puede ocurrir que una página se desactualiza, un error se cuela o simplemente Ud. puede mirar una página y pensar «Bueno, hay una mejor manera de explicar esto». Si ese es el caso y por alguna razón no ha podido resolverlo por sus propios medios, existen tres formas de hacernos conscientes del problema:

  1. Cree un asunto en los SpongeDocs Github <https://github.com/SpongePowered/SpongeDocs/issues>`_
  2. Crear una publicación en la Categoría “Foros de los SpongeDocs <https://forums.spongepowered.org/c/sponge-docs >” _
  3. Visítenos en el “canal de #spongedocs en irc.esper.net <ircs://irc.esper.net:6697/#spongedocs>`_(necesita registrarse)

Escribiendo los documentos

Los Cambios y adiciones a los SpongeDocs deben consignarse como una solicitud de extracción en el _ “SpongeDocs repositorio en GitHub <https://github.com/SpongePowered/SpongeDocs >”_. Nosotros no requerimos que quede perfecto de inmediato, ya que es común para las solicitudes de extracción depurarse durante el proceso de revisión. Las explicaciones incompletas también son bienvenidas, así que no se intimide si no entiende algunas partes. Siempre habrá alguien capaz de llenar los vacíos.

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 forums or #spongedocs on irc.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. Contributors implicitly accept this licensing.

Guía de Estilo

Para asegurarnos que tenemos formatos consistentes a través de todas las paginas de SpongeDocs, aquí le indicamos los lineamientos que hemos desarrollado para la escritura de los documentos Sponge. Esta lista podría recibir adiciones (o modificarse) a medida que el documento crezca.

  1. Los Encabezados Deberían Escribirse en Mayúscula (<- ejemplo) [a menos que aplique la #8].
  2. Los encabezados de las paginas deberían ser significativos (el encabezado aparece como un enlace).
  3. El código del programa debería estar contenido en “inline literales <http://docutils.sourceforge.net/docs/ref/rst/roles.html#literal >” __ o código bloque.
  1. Tratar de no colocar demasiado texto en los código bloque, ya que no pueden ser traducidos. Se recomienda a los colaboradores que no comenten en los código bloque siempre que sea posible. El texto simple del marcador de posición puede ser necesario en algunos ejemplos. Idealmente, los ejemplos de código bloque serán cortos y seguidos de una explicación para cada ejemplo en el cuerpo del texto. Por supuesto, habrán algunos conceptos que no puedan ilustrarse con un ejemplo corto.
  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. Mantener áreas separadas para los Usuarios, desarrolladores de complementos y desarrolladores Sponge.
  2. Evitar la repetición compartiendo paginas siempre que sea posible
  3. Enlace a recursos externos en lugar de reproducirlos.
  1. Algunas excepciones están hechas con fines de traducción.
  1. Hacer distincion entre SpongeForge, SpongeVanilla y SpongeAPI.
  2. Si esto se ve horrible en su lenguaje, invente tus propias reglas.
  3. Sponge es el título del proyecto y NO debe ser traducido.
  1. Algunos idiomas también pueden desear utilizar una traducción fonética.
  1. Automated translations (e.g. Google Translate) are strongly discouraged. These often contain serious errors, and are very likely to be rejected.
  2. Los Titulos de Pagina y Cabeceros de Sección deben estar en texto simple, evitando bloques literales y otros formatos.
  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. Las lineas no pueden tener más de 120 letras.
  5. Los datos importados deben ser escritos en bloque de código la primera vez en la que se les hace referencia en el artículo, pero luego no debe repetirse.

Nota

Como Sponge esta todavía en un estado de flujo, un déficit de desarrollo de documentos es de esperar. Hasta el lanzamiento oficial de Sponge, seguramente habrá vacíos en muchos temas. Sin embargo, SpongeDocs es un documento vivo, siempre sujeto a edición. Nunca va a ser perfecto, sólo golpeado para formarlo según las necesidades de la demanda.

Contribuciones, sugerencias y correcciones son siempre bienvenidas.