Contribuir a la documentación
*****************************
.[perex]
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|coding-standard] en los ejemplos de código.
Aprenda también la [sintaxis |syntax]. Para previsualizar el artículo mientras escribe puede usar el [editor de vista previa |https://editor.nette.org/].
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 |https://www.deepl.com/translator] 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 |https://github.com].
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 |https://editor.nette.org/] 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 |https://rogerdudler.github.io/git-guide/] y plantearse usar alguno de los muchos [clientes gráficos |https://git-scm.com/downloads/guis] disponibles.
Edite la documentación así:
1) En GitHub, cree un [fork |https://help.github.com/en/github/getting-started-with-github/fork-a-repo] del repositorio [nette/docs |https://github.com/nette/docs].
2) [Clone |https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository] ese repositorio en su ordenador.
3) Después, haga los cambios en la [rama correspondiente |#Estructura de la documentación].
4) Compruebe si hay espacios sobrantes en el texto con la herramienta [Code-Checker |tools: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|https://help.github.com/articles/creating-a-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 |https://github.com/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.
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í:
- En GitHub, cree un fork del
repositorio nette/docs.
- Clone ese
repositorio en su ordenador.
- Después, haga los cambios en la rama correspondiente.
- Compruebe si hay espacios sobrantes en el texto con la herramienta Code-Checker.
- Guarde (commit) los cambios.
- Si está satisfecho con los cambios, súbalos a GitHub, a su fork.
- 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.