Formato para documentar???
En javahispano hace algun tiempo intentamos crear un estandard XML para los articulos. La idea era buena y como resultado obteniamos artículos de formato/color uniforme en pdf y html. El problema era conseguir que las personas que nos enviaban los artículos los enviaran en este formato y traducir todo lo que nos enviaban era un arduo y espeso trabajo
Ahora me encuentro ante el problema de elegir como documentar. Tengo varias opciones
- Openoffice, los pros son que tengo un editor de verdad para insertar imagenes tipos de letra y crear plantillas. EL contra es que no veo forma de subir los binarios al CVS y hya muchas gente q no usa openoffice y q quizas no quiera instalarlo solo para documentar cáñamo
- HTML, me creo un pequeño css y escribo html usando algun editor tipo nvu o a pelo que total para poner brs y imgs no es muy dificil
- Emillan me hablo alguna vez de forrest, proyecto de apache, que genera web staticas y dinámicas basado en cocoon, que exporta a pdf y alguans cosillas más
- Docbook, esto parece que es lo mas estandard, pero parece demasiado complejo. Creo haber visto alguna vez algun plugin para el openoffice que permita crear documentos facilemente. Algo q ayudaria mucho.
Vosotros que usais??
Otra opción es LaTeX. Lo he usado para documentar el trabajo de una asignatura y es una maravilla. Pones \tableofcontents y te genera el Ãndice. Aunque eso con las herramientas para docbook también se hace. LaTeX es muy bueno sobre todo para escribir fórmulas matemáticas. También hay un montón de cosas muy útiles en LaTeX como un paquete para incrustar trozos de código con highlighting y numeración de lÃneas.
Por otro lado, has pensado la posibilidad de usar un wiki?
Enviado por gimenete en septiembre 04, 2005 a las 11:12 PM CEST #
Umm... lo del wiki no lo habia pensado, no me parece ninguna tonteria.
Se podría exportar un pdf para generar un manual impreso o algo asi?
Enviado por lasterra en septiembre 05, 2005 a las 12:17 AM CEST #
docbook.
Aunque el xml puede parecer algo complejo, es un estandar con solera y dispone de un monton de utilidades y scripts de transformacion.
Enviado por jaikio en septiembre 05, 2005 a las 08:55 AM CEST #
Yo optarÃÂa por el wiki, es la única forma de hacerlo online y que varias personas lo puedan hacer a la vez. Utilizar docbook o cualquier otra cosa serÃÂa más bien para "un libro estático", y te encontrarÃÂas en el mismo problema de tener que subir la web, etc.
Además, SF y jH.net soportan PHP, no?. No deberÃÂa ser difÃÂcil. También para Licurgo.
Enviado por Al en septiembre 05, 2005 a las 09:45 AM CEST #
Si quieres un wiki hecho en java ;-D y con exportación a pdf ---> xwiki
La última vez que lo probé tenÃa varios bugs gordillos, pero han pasado ya como 5 meses y puede que este mejor.
Enviado por ibon en septiembre 05, 2005 a las 05:21 PM CEST #
Interesante post.
Tengo en mente un artÃculo para jH y el XML de jH no me satisface demasiado.
Como "usuario", si lo tengo que escribir en XML, prefiero hacerlo en Docbook/XML, que es estándar. LaTeX está bien, pero el problema es que la sintaxis que tiene no es estricta y los ficheros pueden acabar guarreados (por eso se evolucionó hacia Docbook/XML).
Por tanto, ¿que deberia usar para un articulo para jH?
Enviado por mariscal en septiembre 05, 2005 a las 09:31 PM CEST #
Nuestra experiencia personal con la utilizacion de wikis es bastante fustrante.
Aunque permite de forma dinamica y sencilla generar contenidos, el hecho que esta informacion este desestructurada es problematico, dado que:
- no permite exportaciones sencillas a otros wikis o herramientas
- el formato de los contenidos es heterogeneo
La utilizacion de docbook no es la llave del universo, pero el hecho de estar en xml y que sea un estandar fuertemente implantado y utilizado (ya casi se le podria considerar un estandar de facto) son, para nosotros, motivos suficientes para la eleccion.
Enviado por jaikio en septiembre 06, 2005 a las 11:51 AM CEST #
Veo Docbook como una solución buena, aunque obviamente implica conocer el formato o usar algun editor que funcione correctamente (espero que openoffice 2 funcione bn)
Luego para poder integrarlo dentro de un proyecto como canyamo o licurgo serÃa necesario algun generador de HTML para que la documentación este visible en internet, y si esta web se genera al hacer el commit del docbook en el cvs... ya ni te digo.
Gracias por vuestras propuestas.
Enviado por lasterra en septiembre 06, 2005 a las 01:05 PM CEST #
Hablando del wiki... se podria aplicar esto a javaHispano? es decir, un wiki hispano al estilo de http://wiki.java.net pero con informacion, articulos, tutoriales, documentacion, tips, etc sobre java. Igual esto anima un poco a la comunidad para participar mas, etc... obviamente muchas de estas cosas ya las cubre javahispano.org pero quiza esta sea una buena forma de animar a la comunidad a colaborar, no creeis?
Saludos!!!
Enviado por flamel en septiembre 06, 2005 a las 01:47 PM CEST #