Cómo contribuir a la documentación

Contribuir a la documentación es una de las actividades más gratificantes, ya que ayudas a otros a comprender el framework.

¿Cómo escribir?

La documentación está destinada principalmente a personas que se están familiarizando con el tema. Por lo tanto, debe cumplir varios puntos importantes:

Comienza por lo simple y general. Pasa a temas más avanzados solo al final.
Intenta explicar el asunto lo mejor posible. Por ejemplo, intenta explicar primero el tema a un colega.
Proporciona solo la información que el usuario realmente necesita saber sobre el tema dado.
Verifica que tu información sea realmente veraz. Prueba cada fragmento de código.
Sé conciso: reduce a la mitad lo que escribas. Y luego, si es necesario, hazlo de nuevo.
Ahorra en todo tipo de resaltados, desde negrita hasta recuadros como .[note].
En los códigos, sigue el Estándar de codificación.

Adopta también la sintaxis. Para previsualizar el artículo mientras lo escribes, puedes usar el editor con vista previa.

Versiones lingüísticas

El idioma principal es el inglés. Si el inglés no es tu punto fuerte, usa DeepL Translator y otros revisarán tu texto. Los cambios deben enviarse en inglés.

La traducción a otros idiomas se realizará automáticamente después de la aprobación y ajuste de tu modificación.

Ediciones triviales

Para contribuir a la documentación, es esencial tener una cuenta en GitHub.

La forma más sencilla de realizar un pequeño cambio en la documentación es utilizar los enlaces al final de cada página:

Mostrar en GitHub abre la versión fuente de la página dada en GitHub. Luego, simplemente presiona el botón E y puedes comenzar a editar (es necesario haber iniciado sesión en GitHub).
Abrir vista previa abre el editor, donde puedes ver directamente la apariencia visual resultante.

Dado que el editor con vista previa no tiene la opción de guardar cambios directamente en GitHub, es necesario, después de completar las ediciones, copiar el texto fuente al portapapeles (con el botón Copy to clipboard) y luego pegarlo en el editor de GitHub. Debajo del campo de edición hay un formulario para enviar. Aquí, no olvides resumir brevemente y explicar el motivo de tu modificación. Después de enviar, se crea una llamada pull request (PR), que se puede editar más.

Ediciones mayores

Más apropiado que usar la interfaz de GitHub es estar familiarizado con los fundamentos del trabajo con el sistema de control de versiones Git. Si no dominas Git, puedes consultar la guía git – the simple guide y, opcionalmente, utilizar alguno de los muchos clientes gráficos.

Modifica la documentación de esta manera:

en GitHub, crea un fork del repositorio nette/docs
clona este repositorio en tu ordenador
luego, en la rama apropiada, realiza los cambios
comprueba si hay espacios sobrantes en el texto usando la herramienta Code-Checker
guarda los cambios (haz commit)
si estás satisfecho con los cambios, envíalos (haz push) a GitHub a tu fork
desde allí, envíalos al repositorio nette/docs creando una pull request (PR)

Es común recibir comentarios con sugerencias. Sigue los cambios propuestos e incorpóralos. Añade los cambios propuestos como nuevos commits y vuelve a enviarlos a GitHub. Nunca crees una nueva pull request para modificar una pull request existente.

Estructura de la documentación

Toda la documentación se encuentra en GitHub en el repositorio nette/docs. La versión actual está en master, las versiones anteriores se encuentran en ramas como doc-3.x, doc-2.x.

El contenido de cada rama se divide en carpetas principales que representan las áreas individuales de la documentación. Por ejemplo, application/ corresponde a https://doc.nette.org/es/application, latte/ corresponde a https://latte.nette.org, etc. Cada una de estas carpetas contiene subcarpetas que representan las versiones lingüísticas (cs, en, …) y, opcionalmente, una subcarpeta files con imágenes que se pueden insertar en las páginas de la documentación.