Otro repositorio más

Added by Alejandro Roca Alhama almost 7 years ago

Voy a crear un nuevo repositorio docaux para aquellos documentos que vayamos generando que no tengan relación directa con el proyecto.

Lo comento porque este finde he redactado un pequeño mini HOWTO sobre DocBook (en DocBook claro), incluyendo instalación, uso con Emacs y un conjunto de convenciones a utilizar, muchas de ellas de las que usa la propia gente de OpenStack. Está sin terminar, pero creo que lo puedo acabar entre hoy y mañana (si me dejan). Si lo consideráis interesante lo pongo en GIT y lo vamos mejorando y completando con lo que vayamos aprendiendo. Si por lo que sea se presentan más documentos de este tipo los podemos ir subiendo ahí. Otro documento intersante sería una pequeña guía sobre el uso de GIT. Si alguien se apunta que lo diga.

También ha comentado Alberto que estamos de momento con tres repositorios, si no sería mejor unificarlos en uno solo. Yo creo que sí.

¿Qué hacemos? ¿Todo en uno o un repositorio por documento? La gente de OpenStack tiene uno solo y en cada directorio un documento, con un directorio "common" para el temas de imágenes y secciones compartidas.

De esta forma podríamos seguir esta estructura:

documento1
----documento1.xml
----ch_nombre_capitulo1.xml
----ch_nombre_capitulo2.xml
----figures (directorio)
----samples (directorio)
documento2
----documento2.xml
----ch_nombre_capitulo1.xml
----ch_nombre_capitulo2.xml
----figures (directorio)
----samples (directorio)
common
----figures (directorio)
----ch_nombre_capitulo_compartido.xml (justificación del proyecto y cualquier otra sección que deba aparecer en todos los documentos)
----seccion_compartida.xml

¿Cómo lo veis?


Replies (14)

RE: Otro repositorio más - Added by Alberto Molina Coballes almost 7 years ago

Yo creo que la mejor opción es tener un solo repositorio, así que si os parece bien a los demás, lo unificamos.

Jesús Moreno, que tiene que lucir la estancia en Londres, se ha comprometido firmemente a traducir al inglés todos los documentos que generemos ¡¡¡y había testigos cuando lo dijo !!!, así que ahora no se puede echar atrás XD, también habría que ver la forma más eficaz de hacer esto, ¿se os ocurre cómo?

RE: Otro repositorio más - Added by Alejandro Roca Alhama almost 7 years ago

Sí, un solo repositorio es lo mejor. Importante el directorio common y mantener una estructura común.

¿Voluntario para traducir todo? ¿A qué hora dijo eso?

Lo de la traducción lo veo complicado y de momento un objetivo más que secundario, pero tampoco le vamos a quitar la ilusión al chiquillo :)

Que empiece a mirar: http://w3c.es/Divulgacion/GuiasBreves/internacionalizacion

:)

RE: Otro repositorio más - Added by Jesús Moreno León almost 7 years ago

No sé a qué hora lo dije y tampoco recuerdo haber dicho que fuera a traducir todos los documentos... Pero bueno, de momento, ya he comenzado: http://informatica.gonzalonazareno.org/openstack/wheezy_en/

RE: Otro repositorio más - Added by Alberto Molina Coballes almost 7 years ago

¡Qué cosas se dicen a según qué horas! ;), por cierto, el enlace que pone Alex, puede ser muy interesante, porque en lugar de hacer dos documentos, podemos utilizar etiquetas, de esa manera es más fácil simultanear los dos trabajos, ¿no?

RE: Otro repositorio más - Added by Alejandro Roca Alhama almost 7 years ago

Sí es más fácil, pero es mucho más trabajo (casi el doble) sin contar la parte técnica que aún no sabemos cómo se resuelve. XML soporta de forma nativa la internacionalización, pero la verdad es que ahora mismo hay muchas cosas que hacer y, hablo por mí, ponerme con eso me da una pereza, sobretodo habiendo un montón de cosas más interesantes que hacer.

Por mí lo de la traducción al inglés lo dejaría para más tarde, para mucho más tarde. ¿No?

RE: Otro repositorio más - Added by Alberto Molina Coballes almost 7 years ago

Aparte de la broma a Jesús, podemos ver la traducción en los dos sentidos. Evidentemente para nosotros no es una prioridad, traducir nuestra documentación al inglés, pero tened en cuenta que toda la documentación de OpenStack está en docbook con licencia CC-BY-SA, por lo que podemos utilizar párrafos completos, traducir al castellano y a la vez dejar el párrafo en inglés, ¿no es una ventaja?

RE: Otro repositorio más - Added by Alejandro Roca Alhama almost 7 years ago

Es una ventaja sí, pero aparte de traducir e incluir párrafos completos también vamos a tener documentación más o menos original.

¿Realmente os apetece documentar haciendo el doble de trabajo?, lo digo porque a mí no, habiendo como ahora un montón de cosas que hacer y un montón de cosas que resolver. Estamos hablando que cada vez que en Docbook metamos un párrafo, un título, un enlace, una tabla, un lo que sea hay que hacerlo en el peor de los casos dos veces, con todo lo que eso conlleva. Hablo por mí, pero de momento me aterra hasta la idea. Vamos a generar la documentación y después cuando el core básico de lo que queremos esté documentado y revisado, si queréis empezamos con las traducciones, y nos posicionamos como el grupo español que abandera el proyecto OpenStack más allá de las fronteras norteamericanas, pero de momento vamos a utilizar nuestros escasos recursos inteligentemente, que llega Julio y a ver con quién contamos realmente en julio con el calor y la playita.

De todas formas no le quiero quitar a nadie las ganas de trabajar, faltaría más, el que quiera ir traduciendo que lo vaya haciendo :) Pero yo creo que se nos está yendo la cabeza :P

RE: Otro repositorio más - Added by Alberto Molina Coballes almost 7 years ago

He creado el repo doc en el que he añadido todo lo hecho hasta ahora en los otros repos y he cambiado a la estructura propuesta por Alex. Los que me habéis pasado un usuario de github, recibiréis por correo la notificación de que habéis sido agregados al nuevo repositorio.

Si os parece bien dejamos de utilizar el resto de repositorios y si todo está bien, en unos días los borramos.

A los que estáis trabajando con los repositorios antiguos: Clonar el repo doc y trabajar en los subdirectorios de éste.

RE: Otro repositorio más - Added by Alejandro Roca Alhama almost 7 years ago

Oído cocina!!!

Alex.

RE: Otro repositorio más - Added by Miguel Ángel Ibáñez Mompeán almost 7 years ago

Mejor, menos jaleo.

Ya lo habréis visto por github, pero quien no pues tb. le conviene clonarse https://github.com/openstack/openstack-manuals.git (mucho docbook para (aprender|leer|citar|copiar|pegar)* en su caso.

Salud

RE: Otro repositorio más - Added by Alejandro Roca Alhama almost 7 years ago

Sí, le hemos estado echando un vistazo y la verdad es que la gente del proyecto de documentación de OpenStack lo tiene muy buen montado.

Se puede aprender un montón viendo cómo organizan y generan su documentación. Lo que aún no he podido ver, después de leer un par de ficheros pom.xml de Maven es dónde narices personalizan la hoja de estilos.

RE: Otro repositorio más - Added by Alejandro Roca Alhama almost 7 years ago

La encontré, la hoja de estilos está en el fichero:

~/.m2/repository/com/rackspace/cloud/api/clouddocs-maven-plugin/1.3.1/clouddocs-maven-plugin-1.3.1.jar

Junto con todas las imágenes que generan la portada + todos los iconos que usan y demás.

Tipos de letra y demás cambios se pueden encontrar dentro del .jar en: cloud/fo/docbook.xsl

Aunque la verdad que no tengo problema en usar el mismo estilo que usan ellos modificando ligeramente la portada (es un SVG) y los colores de los títulos, si acaso :)

RE: Otro repositorio más - Added by Alberto Molina Coballes almost 7 years ago

Creo que está clara la opción de Maven, también lo estuve probando ayer y es mucho más cómodo y potente que utilizar directamente xsltproc, voy a poner una tarea para todo lo que se refiere a Maven, hoja de estilo y demás, ¿a que no sabéis a quién se le va a signar? ;)

RE: Otro repositorio más - Added by Alejandro Roca Alhama almost 7 years ago

No me lo digas... o a mí o a tí.

:)

(1-14/14)