Escribir documentación
No dudes en señalar issues en esta documentación o, si no encuentras el repositorio adecuado, problemas con las propias herramientas. (¡Cuantos más comentarios, mejor!) Si quieres proponer texto nuevo para la documentación, ¡puedes hacer esos cambios con el enlace "Editar esta página" al final de cualquier página y enviando una pull request!
Introducción
Este documento es una guía para la documentación de OpenFn. Recuerda que el objetivo es tratar "la documentación como código" y crear un portal de documentación que permita usar las herramientas de OpenFn de forma bastante autónoma. Puedes contribuir a este documento.
Qué es la documentación
Cuando hablamos de documentación, nos referimos a información concisa, precisa y que evoluciona rápido, que ayuda a los integradores ciudadanos que usan OpenFn a entender las interfaces complejas de la plataforma. ¿Qué significa tratar la documentación como código? Guardar los archivos fuente en un sistema de control de versiones. Generar los artefactos de la documentación automáticamente. Asegurarse de que un grupo de revisores de confianza revise la documentación minuciosamente. Publicar los artefactos con poca intervención humana.
(Fuente: el libro de Anne Gentle Docs Like Code.)
Objetivos de esta documentación
Promover la colaboración
Colabora con los contribuidores de forma eficiente: mantén la documentación en el mismo sistema que el código y genera los entregables a partir de archivos fuente.
Conseguir contribuciones de cola larga
Divide los entregables en partes que animen a hacer contribuciones pequeñas pero valiosas. Ya no hace falta que una sola persona se encargue de todo un entregable de documentación.
Seguir los bugs de la documentación como los bugs del código
Cuando corrijas un bug de la documentación, menciona ese bug en el mensaje del commit para que los revisores puedan juzgar si la corrección resuelve el problema planteado.
Conseguir revisiones rápidas y de calidad de los miembros del equipo
Confía en que los miembros del equipo valoren la documentación, garanticen la precisión técnica y la coherencia, respeten las necesidades de los usuarios finales y defiendan los mejores entregables de documentación para sus lectores.
Hacer documentación atractiva
El diseño es importante. Crea documentación atractiva y moderna.
Usar herramientas y flujos de trabajo de desarrollo
Automatiza el proceso lo más posible para que podamos centrarnos en crear contenido.