El rediseño de gentoo.org, Parte 2: El renacimiento de un sitio1. El sistema de documentación Si ha leído la primera entrega de mi serie sobre el rediseño de gentoo.org, entonces sabrá que soy el arquitecto jefe de Gentoo Linux y me hago responsable del sitio Web Gentoo Linux. Y, ahora mismo, el sitio deja mucho que desear. Sí, parece atractivo, pero cuando se mira detrás de los cucos gráficos, se observará que realmente no atiende las necesidades de su público objetivo principal: los desarrolladores, usuarios y usuarios potenciales de Gentoo Linux. Anteriormente, usé un enfoque de diseño centrado en el usuario para crear una lista de prioridades para el sitio, y entonces usé estas prioridades para crear un plan de acción para modernizar gentoo.org. Dos cosas eran las primeras en la lista de prioridades: nueva documentación para el desarrollador y una nueva lista de correo para comunicar a los desarrolladores los cambios realizados a nuestro repositorio CVS. Aunque que añadir la nueva lista de correo CVS era relativamente fácil (pero como verá más adelante, era más difícil de lo que había pensado), la nueva documentación del desarrollador requería mucha planificación y trabajo. No solo necesitaba crear alguna documentación (una tarea que había estado ignorando durante demasiado tiempo), también había elegido una sintaxis XML oficial que nuestra documentación maestra usaría. Verá, hasta hacía unos pocos meses yo había estado creando la documentación en HTML puro. Esto era definitivamente una tarea bastante desagradable, porque haciendo esto, el contenido se había mezclado (la información real) con la presentación (las etiquetas HTML relacionadas con la visualización). ¿Y en qué acabó todo esto? Un jaleo inflexible, en eso acabó. Era duro editar la documentación y extremadamente difícil hacer mejoras HTML en todo el sitio. En este artículo, orgullosamente demuestro la nueva solución flexible XML para la documentación. Pero primero, resumiré mi experiencia cuando añadí la lista de correo del registro CVS a nuestro sitio. Añadiendo la lista de correo del registro CVS El objetivo de la lista de correo de registro CVS es informar a los desarrolladores, de los nuevos commits realizados en nuestro repositorio. Ya que tenía instalado el gestor de listas de correo mailman (mire Recursos), pensé que crear esta nueva lista sería sencillo. Primero, simplemente crearía la lista de correo, entonces añadiría el "hook" apropiado al repositorio CVS de forma que los correos electrónicos pudieran ser generados automáticamente y enviados, describiendo los cambios a nuestros fuentes cuando estos se produjeran. Primero comencé investigando un fichero especial en el CVSROOT de mi repositorio llamado "loginfo". Teóricamente, modificando este fichero, podría ordenar a CVS que ejecutara un guión cada vez que se realizaba un commit (y por lo tanto una modificación) en el repositorio. Por lo que creé un guión especial loginfo y lo conecté a mi repositorio actual. Y de hecho enviaba correos electrónicos a la nueva lista de correo "gentoo-cvs" cada vez que se realizaban modificaciones a nuestros fuentes. Desafortunadamente, esta solución no era todo lo que yo esperaba. En primer lugar, generaba muchos mensajes de correo electrónico -- uno por cada fichero modificado -- y en segundo lugar, los mensajes eran crípticos ¡y en algunos casos incluso estaban vacíos!. Rápidamente eliminé mi guión loginfo y dejé el proyecto de la lista de correo gentoo-cvs en espera. Estaba claro que el hook para CVS loginfo no era apropiado para mis necesidades y lo pasé mal revisando cualquier información relacionada con loginfo que pudiera ayudarme a resolver el problema. Algunas semanas más tarde, empecé a buscar una alternativa para loginfo. En esta ocasión de forma inteligente eché un vistazo a http://freshmeat.net. Allí encontré rápidamente lo que estaba buscando: el increíblemente maravilloso guión perl cvs2cl.pl disponible en http://red-bean.com (mire en Recursos). En lugar de usar el hook loginfo, cvs2cl.pl usa el comando cvs log para conectar directamente al repositorio y extraer la información del registro relevante y apropiada. También, en lugar de escupir mensajes de registro CVS relativamente crípticos, hace un gran trabajo en reformatearlo todo a un formato de ChangeLog legible.
cvs2cl.pl también puede ser instruido para que genere salida en formato XML, y en mi próximo artículo, me aprovecharé de esto para incorporar un ChangeLog totalmente actualizado en la nueva sección de desarrollo de nuestro sitio. A continuación se muestra el guión que ahora uso para generar correos electrónicos diarios de ChangeLog. Primero, cambia el directorio actual de trabajo al lugar donde se encuentra el repositorio CVS a comprobar. Entonces, crea las variables de entorno $yesterday y $today que contienen las fechas apropiadas en formato RFC 822. Notar que ambas variables de fecha tienen puesta la hora a las "00:00" o medianoche. Estas variables son usadas alternativamente para crear la variable $cvsdate que es pasada al guión cvs2cl.pl para especificar el rango de fechas en el que estoy interesado -- el lapso de tiempo desde ayer a media noche hasta hoy a media noche. Así, la variable $cvsdate contiene un datespec que informa a cvs2cl.pl para que registre solo los cambios realizados el día de ayer, pero no otros. Además, también creé una variable $nicedate (usada en el asunto del correo) y usé el mailer mutt (en modo compatibilidad con mailx [mire Recursos]) para enviar el correo a la lista de correo gentoo-cvs:
Usando cron, ejecutaba este guión cada día a media noche. Gracias a cvs2cl.pl mis desarrolladores ahora obtienen las actualizaciones realizadas en CVS de manera precisa y legible. Ahora vamos por el proyecto de documentación de Gentoo Linux. Nuestro nuevo sistema de documentación envuelve dos grupos de personas o públicos objetivo: los creadores de la documentación y los lectores de la documentación. Los creadores necesitan una sintaxis XML bien diseñada que no se les cruce en el camino; los lectores, que no se preocupan del XML, quieren documentación generada en HTML que sea funcional y atractiva. El reto de la implementación es reunir un sistema completo que atienda las necesidades de los dos públicos. ¡Ah! y supongo que hay un tercer "público" -- yo, el webmaster y la persona diseñando el nuevo sistema. Ya que yo voy a interactuar con el nuevo sistema de documentación siempre que el sitio es actualizado, necesito que sea fiable y flexible. Primero hablemos un poco sobre el HTML preparado para la Web que será generado a partir de los ficheros XML. Para hacer una documentación buena y legible, necesitaré tener soporte de las etiquetas XML apropiadas. Por ejemplo, la capacidad de insertar notas, mensajes importantes y advertencias en el cuerpo del documento (y mostrarlas de forma destacada en el HTML resultante) es imperativa. También debo ser capaz de insertar bloques de código, y sería bueno si las aportaciones del usuario real pudieran de alguna forma reflejarse en la salida del programa. Podría incluso añadir etiquetas que resaltaran los comentarios en el código fuente en un color alternativo de forma que los bloques de código fueran más legibles. Los documentos deberían tener un índice (con hiperenlaces a los capítulos apropiados), una sinopsis, una fecha de revisión, versión y una lista de autores al comienzo del documento. Y, por supuesto, cada documento debería tener una cabecera en la primera parte de la página, conteniendo un pequeño logo de Gentoo Linux. Pinchar en este logo debería llevarte de vuelta a la página principal de Gentoo Linux. Y lo último pero no lo menos importante, cada documento debería tener un pie que contuviera información de copyright junto con un correo electrónico de contacto. Esto era una sólida lista de requisitos, y decidí concentrarme en la parte más entretenida en primer lugar: el nuevo logo de Gentoo Linux que debía aparecer en la parte superior izquierda de cada documento de Gentoo Linux. Usé la "g" del gráfico de "gentoo" (creado usando el libre y excelente programa Blender 3D) en nuestra página principal como base para un logo más pequeño. Jugué un poco con los ajustes de extrusión y añadí un mapa de entorno chrome. Finalmente coloqué las luces y la cámara y el nuevo logo estaba terminado. Después de importarlo en Xara X (mire Recursos) y añadiendo algún texto, este fue el resultado:
Usé este nuevo logo como inspiración para el resto de la combinación de colores HTML, usando un tema morado en todo momento. Hice bastante uso de las hojas de estilo en cascada (CSS) para controlar los atributos y el espaciado de las fuentes. Una vez que tenía preparado un prototipo decente, comencé a centrarme en las partes internas de la nueva documentación -- la nueva sintaxis XML. Quería que la sintaxis fuera tan simple como posible, por lo que creé las etiquetas XML justas para una organización apropiada del documento, pero no más. Entonces comencé a trabajar en las XSLT para transformar el XML en el HTML destino. Después de muchos ajustes y unas buenas aportaciones de uno de mis desarrolladores, el nuevo sistema de documentación alcanzó el punto en el que estaba preparado para ser usado. Comencé a trabajar inmediatamente en nuestra primera guía de desarrollo, "La Guía de Documentación de Gentoo Linux" (xml-guide.html), que contiene una descripción completa del nuevo formato XML. No solo permitía esto a otros desarrolladores empezar a trabajar en el nuevo estilo de documentación, sino también servía a como un excelente ejemplo del nuevo sistema de documentación en acción. Asegúrese de leer esta guía para adquirir un conocimiento completo de nuestra nueva sintaxis XML. Si está trabajando en su propia solución para la documentación, querrá considerar también los formatos XML y SGML de DocBook (mire Recursos). DocBook está bien preparado para documentación técnica de gran escala y proyectos libro, es muy flexible y tiene muchas (quizá demasiadas) características. Además, existe un número de paquetes que pueden ser usados para convertir XML and SGML de DocBook a formatos como páginas man, texinfo, Postscript, PDF y por supuesto HTML. No elegí DocBook ya que una sintaxis XML ligera atendería mejor las necesidades de Gentoo Linux. Ahora mismo, nuestra sintaxis de la guía XML tiene cerca de 20 etiquetas y unos 10 atributos. Un conjunto de etiquetas limitado hace que la guía XML sea fácilmente transformable en otros formatos como HTML y también asegura un cierto nivel de consistencia a lo largo del conjunto total de nuestra documentación, ya que el formato es muy simple. Como tengo mi propio formato XML, seré capaz de extender el formato con nuevas etiquetas según las necesite. Me gusta tener este nivel de control. Veo XML como una tecnología que debería ser usada por la gente para que estructurara sus datos de la forma que le resultara más sencilla. En otras palabras, la capacidad de definir tus propios elementos y atributos es algo precioso, y debo aprovecharme de ello. Después de todo, estoy definiendo una característica de XML. Desde luego, crear tu propia sintaxis XML no es siempre la mejor solución, especialmente cuando el intercambio de datos es importante para. Entre todo el bombo publicitario de XML, una cosa que siempre se pasa por alto es que la conversión desde y a diferentes formatos XML puede ser extremadamente difícil. En muchos casos, los dos formatos no serán 100% compatibles, y tendrá la desagradable disyuntiva entre generar datos y/o metadatos, evitando intencionadamente el uso de ciertos elementos y atributos, o crear un "superformato" que adapte los datos y los metadatos para ambos formatos XML. En el mundo de la documentación, DocBook es una excelente opción como un "superformato" porque es muy flexible; puede fácilmente adaptar documentación importada de variedad de fuentes. Sin embargo, la riqueza y la flexibilidad de DocBook puede también crear problemas. Por ejemplo, aporta cientos de etiquetas que nunca necesitará, y dando soporte a estas etiquetas en su XSLT puede hacer la conversión a otros formatos más difícil. Así, mientras DocBook es un excelente contenedor para documentación convertida desde otros formatos, su propia sintaxis XML minimalista podrá ser casi siempre fácilmente convertida a otros formatos. Lo más importante es evaluar con cuidado cualquier solución potencial mientras se mantienen las necesidades de su público(s) objetivo en mente. Con el nuevo sistema de documentación funcionando, convertí todos nuestros documentos al nuevo formato y publique los nuevos documentos en nuestro sitio. Además, creé un enlace a la página de suscripción a la lista de correo gentoo-cvs. La clave aquí es que integraba estas características en el sitio de forma que los usuarios pudieran beneficiarse de las mejoras cuanto antes.
|
|
