Soy el creador de un creciente proyecto de código abierto. Actualmente, me siento frustrado tratando de encontrar la mejor manera de administrar la documentación. Estas son las opciones que he considerado:
- Sitio web HTML
- Wiki de Github
- Archivos de rebajas alojados en Github
- Colocación de todos los documentos en Github README.md
La documentación ya está escrita en Markdown, simplemente no puedo entender cómo quiero que esté disponible. Estoy realmente atraído por Git ya que puedo ramificar y etiquetar la documentación al igual que puedo ramificar y etiquetar la fuente.
Podría usar una biblioteca Markdown para traducir el Markdown a HTML y mostrarlo en un sitio web con estilo. Tendría que cargar los cambios en el sitio web cada vez que hubiera un cambio, y sería difícil administrar todas las diferentes "etiquetas" de la documentación.
Los wikis de Github (que yo sepa) no cambian según la rama en la que se encuentre. Por lo tanto, solo podría tener la versión "maestra" de la documentación en forma de Wiki Github en un momento dado.
Ponerlo todo en el archivo README de Github es bastante bueno. Obtengo ramificaciones y etiquetado, pero es un poco agotador de usar y no se presta bien para facilitar la navegación.
¿Me estoy perdiendo alguna solución increíble? ¿Qué otras opciones tengo?
fuente
Respuestas:
Una cosa que diría es que la documentación DEBE estar en los archivos de código fuente (usando el marcado que desee) y luego los documentos generados automáticamente a partir de estos.
Al menos en su sitio, puede generar descargas formateadas de los documentos como parte del paquete fuente para que el usuario no necesite una herramienta de documentos específica
La posibilidad de que alguien más arregle / agregue una función y luego edite / agregue un poco de documentación de marcado inmediatamente adyacente en el mismo archivo puede ser baja, PERO la posibilidad de que encuentre un archivo completamente diferente en un repositorio de documentos diferente para hacer lo mismo es ligeramente menos que cero.
Siempre puede tener un tutorial.h que contenga grandes bloques de texto si lo desea, pero trátelo como parte de la fuente
fuente
Si su proyecto es una biblioteca, nada mejor que la documentación de estilo javadoc para documentar la sintaxis de la API a partir de los comentarios dentro del código mismo.
En cuanto a la documentación sobre tutoriales, ejemplos de uso, etc. Recomiendo encarecidamente utilizar un formato wiki. Otros proyectos que he visto tienen páginas separadas para diferentes ramas. Cuando inicia una nueva sucursal, simplemente copia las cosas que no han cambiado a una nueva página y actualiza desde allí.
Mi razón para recomendar una wiki es anecdótica, pero por experiencia personal. He contribuido con actualizaciones de documentación para proyectos de código abierto en varias ocasiones, pero todos han estado en wikis. Si estoy tratando de resolver algo y la documentación es engañosa o inútil, después de resolverlo, actualizaré el wiki mientras estoy en los documentos y está fresco en mi mente. Si no es por una sensación de retribución, al menos porque sé que es probable que deba volver a buscarlo en uno o dos años.
Si no hay una wiki, la barrera de entrada es demasiado alta para molestar, entre averiguar cómo se genera la documentación, dónde se almacena, obtener lo último del control de origen, cómo hacer ediciones, hacer las ediciones reales y navegando por las listas de correo para que se acepte un parche.
Si desea un control estricto sobre su documentación, utilice todos los medios que le resulten más cómodos, ya que en su mayoría será el único que la actualice. Si desea fomentar la participación de la comunidad, use un wiki.
fuente
Markdown Files Hosted with the source funciona extremadamente bien.
Las herramientas docutils basadas en RST , por ejemplo, pueden crear HTML o LaTex (y PDF) a partir de un conjunto de documentos.
Esto, en efecto, combina su opción 1 y la opción 3.
fuente
Si no le importa convertir los documentos de Markdown a reStructuredText, considere Sphinx . Es tan fácil como rebajar, pero es mucho más poderoso.
fuente