Contribuir a la documentación

Contribuir a la documentación es una de las actividades más valiosas, porque ayuda a otros a entender el framework.

¿Cómo escribir?

La documentación está pensada sobre todo para las personas que se acercan al tema por primera vez. Por eso debería cumplir varios puntos importantes:

• Empiece por los conceptos sencillos y generales. Pase a los temas más avanzados solo al final.
• Intente explicar el tema con la mayor claridad posible. Por ejemplo, pruebe a explicárselo antes a un compañero.
• Dé solo la información que el usuario necesita realmente para el tema en cuestión.
• Compruebe que su información es exacta. Pruebe cada fragmento de código.
• Sea conciso: recorte a la mitad lo que escriba. Y luego, si quiere, hágalo otra vez.
• Use el resaltado con moderación, desde el texto en negrita hasta los recuadros tipo .[note].
• Siga el estándar de codificación en los ejemplos de código.

Aprenda también la sintaxis. Para previsualizar el artículo mientras escribe puede usar el editor de vista previa.

Versiones de idioma

El inglés es el idioma principal, así que lo ideal es que sus cambios estén en inglés. Si el inglés no es su fuerte, use el traductor DeepL y otros revisarán su texto.

La traducción a los demás idiomas se hará automáticamente después de que su edición se apruebe y se finalice.

Ediciones triviales

Para contribuir a la documentación necesita tener una cuenta en GitHub.

La forma más fácil de hacer un cambio pequeño en la documentación es usar los enlaces del final de cada página:

• Show on GitHub abre la versión fuente de la página en GitHub. Después basta con pulsar la tecla E para empezar a editar (tiene que haber iniciado sesión en GitHub).
• Open preview abre un editor donde ve de inmediato el aspecto visual final.

Como el editor de vista previa no puede guardar los cambios directamente en GitHub, al terminar de editar tiene que copiar el texto fuente al portapapeles (con el botón Copy to clipboard) y pegarlo después en el editor de GitHub. Debajo del campo de edición hay un formulario de envío. Ahí no se olvide de resumir brevemente y explicar el motivo de su edición. Tras enviarlo se crea un pull request (PR), que se puede seguir editando.

Ediciones más grandes

En lugar de depender solo de la interfaz de GitHub, es mejor conocer los fundamentos del trabajo con el sistema de control de versiones Git. Si no conoce Git, puede consultar git – the simple guide y plantearse usar alguno de los muchos clientes gráficos disponibles.

Edite la documentación así:

1. En GitHub, cree un fork del repositorio nette/docs.
2. Clone ese repositorio en su ordenador.
3. Después, haga los cambios en la rama correspondiente.
4. Compruebe si hay espacios sobrantes en el texto con la herramienta Code-Checker.
5. Guarde (commit) los cambios.
6. Si está satisfecho con los cambios, súbalos a GitHub, a su fork.
7. Desde allí, envíelos al repositorio nette/docs creando un pull request (PR).

Es habitual recibir comentarios con sugerencias. Siga los cambios propuestos e incorpórelos. Añada los cambios sugeridos como commits nuevos y vuelva a subirlos a GitHub. Nunca cree un pull request nuevo solo para modificar uno existente.

Estructura de la documentación

Toda la documentación está en GitHub, en el repositorio nette/docs. La versión actual está en la rama master, mientras que las versiones antiguas están en ramas como doc-3.x, doc-2.x.

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