Escritura de los Spongedocs

Advertencia

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.

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.

Los documentos están escritos en reStructuredText (reST), si Ud esta familiarizado con Markdown (md) el paso a reST no debería ser difícil. Si esta teniendo problemas con esto le sugerimos que se una a nuestros foros forums or `#SpongeDocs <ircs://irc.esper.net:6697/#spongedocs>`_en Esper.net y solicite ayuda allí.

La Documentación de Sponge está bajo la licencia Creative Commons - Share-Alike <https://creativecommons.org/licenses/by-sa/4.0/>`_. Los recursos artísticos están relacionados bajo la licencia Creative Commons - Non Commercial, No Derivatives <https://creativecommons.org/licenses/by-nc-nd/4.0/>`_. Las contribuciones aceptan implícitamente éstas licencias.

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.

  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. Se desalientan las traducciones automáticos (por ejemplo, Google Translate). Muchas veces, estas traducciones contienen errores serios, y probablemente serán rechazados.

  2. Los Titulos de Pagina y Cabeceros de Sección deben estar en texto simple, evitando bloques literales y otros formatos.

  3. Los símbolos de código deberán de estar en mayúsculas en sus formas originales y no tener espacios extras (ej. blockState (nombre de un campo) o BlockState (nombre de una clase), en vez de block state). También deberán de tener un formato como un literal usando backticks (ej. blockState) en el cuerpo del texto.

  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.