Cambios en la documentación de plone.org

El pasado martes 2 de diciembre tuvimos una reunión del grupo de editores de documentación de Plone (el llamado Editorial Board) en la que discutimos una serie de cambios propuestos para la documentación.

JoAnna publicará un resumen del encuentro próximamente ha publicado un resumen de las decisiones que se tomaron aquí, y también una serie de anotaciones y la transcripción de la charleta aquí. Mientras tanto Yo me he tomado la libertad de publicar el mío propio aquí, para el gusto de los motores de búsqueda.

En primer lugar, la documentación se dividirá en parte dos partes:

  • Una oficial, en la que se seguirán procesos de revisión, actualización y control de calidad dirigidos por los editores, pero que puede ser escrita por cualquier miembro de la comunidad de Plone.
  • Una abierta de estilo wiki, con páginas que cualquiera podrá editar sin pasar por el proceso de revisión de la documentación oficial. Se diferenciará claramente de la oficial y se encontrará en un subdominio del tipo algo.plone.org.

Por otra parte, se tiene la intención de usar Sphinx para la documentación de referencia de los módulos que componen Plone. Se llevará a cabo una experiencia piloto con algún módulo para ver qué tal funciona.

La documentación oficial se intentará organizar en manuales sobre cada tema (uso básico, theming, formularios, etc.), cada uno con una introducción rápida primero y luego una guía comprensiva sobre el tema. Se intentará encontrar un lugar en los manuales para toda documentación nueva que se escriba.

Se eliminará la división del Plone Help Center actual por tipo de contenido en la parte oficial, es decir, adiós a las URLs tipo plone.org/documentation/tutorial, plone.org/documentation/howto, etc.

Se intentará que los PLIPs incluyan información para facilitar la tarea de documentar los cambios que introducen. Estamos en contacto con el Framework Team para conseguirlo.

Se eliminarán los comentarios de los artículos oficiales de documentación. Los errores y mejoras de un artículo se registrarán y se administraran con el sistema Trac general de Plone, como bugs en la documentación.

Se eligieron tres cargos especiales en el equipo de documentación:

  • Veda Williamson, responsable de asuntos políticos y de presentación (theming principalmente).
  • Steve McMahon, responsable técnico y enlace con la Plone Foundation.
  • JoAnna Springsteen, pastora de nuestro rebaño de editores.

Esto es todo por el momento.

Por cierto, el plazo de presentación al puesto de editores de documentación de Plone aún está abierto. Quien esté interesada en colaborar, que me avise y nos ponemos en marcha.

Leave a Reply

Your email address will not be published. Required fields are marked *