Necesidades de documentación de usuarios y colaboradores
Probablemente coincidiremos en que la documentación es uno de los principales problemas de la mayoría de proyectos de código abierto, y OpenERP no es una excepción. Afortunadamente, esta regla no siempre se cumple. Algunos proyectos, como PostgreSQL, tienen una documentación excelente, por lo que todavía hay esperanza para los usuarios y los nuevos desarrolladores de OpenERP.
En NaN analizamos los problemas que usuarios, desarrolladores, redactores de documentación y traductores encuentran con la documentación, e intentamos resolverlos con un nuevo módulo de documentación que acabamos de publicar. Se integra con nuestro cliente Koo, pero esperamos que el resto de clientes y desarrolladores de módulos, especialmente OpenERP, se sumen al esfuerzo. Por tanto, creemos que hemos resuelto la mayoría de las preocupaciones y que ahora disponemos de un entorno potente y fácil de usar, a la espera de nuevos colaboradores.
En este artículo explicaré los requisitos que detectamos para cada uno de estos grupos de usuarios y colaboradores, y en otro artículo expondré la solución que dimos a cada uno.
Usuarios
Los usuarios suelen necesitar dos tipos de documentación. Por un lado, quieren un libro que pueda leerse sin tener la aplicación abierta: un documento que permita obtener una visión general de la aplicación y de cómo funcionan e interactúan las cosas. Por otro lado, quieren ayuda cuando la necesitan, mientras trabajan. Por ello, necesitan un icono que puedan pulsar para obtener ayuda contextual mientras introducen información en un documento como una factura. En ambos casos, querrán capturas de pantalla que les ayuden a entender el aspecto de las cosas y, sobre todo, en qué entradas de menú encontrarán lo que están leyendo.
Al mismo tiempo, los usuarios odiarán tener que saber qué módulos están instalados en el sistema. Uno de los principales problemas de la documentación actual es que OpenERP no puede tener un único libro que explique cómo funciona el ERP. Esto sencillamente no tiene sentido, porque OpenERP es altamente extensible y el comportamiento puede variar según los módulos instalados. Tradicionalmente, las aplicaciones han resuelto esta cuestión con una larga lista de “si”, que hace que la documentación sea inutilizable: “si está instalado el módulo X, obtendrá el comportamiento XX; si está instalado el módulo Y, obtendrá el comportamiento YY; si tiene...”. Por tanto, es importante tenerlo presente: no se puede tener un documento con la documentación de OpenERP sin saber qué módulos están instalados.
Desarrolladores
Los desarrolladores odian la documentación, y eso es un hecho. Dicho esto, esta aversión puede reducirse si conocemos los motivos de ese sentimiento.
Una preocupación es que los usuarios nunca leen la documentación, y probablemente hay parte de verdad en esta afirmación. Muchos usuarios no leerán todo el libro de OpenERP, pero utilizarán, por ejemplo, la ayuda proporcionada en los campos, y eso también es documentación. Es lo que llamamos ayuda contextual, o la ayuda cuando la necesitan.
Otra preocupación es que escribir documentación de alguna manera “rompe” el proceso de programación. En muchos casos, el desarrollador no escribió documentación que explicara qué hace el módulo, pero sí utilizó textos de ayuda en varios campos clave. Por tanto, parece que esta preocupación tiene fundamento, y mantener la documentación en un repositorio separado y sin vincularla a las versiones y cambios de los módulos tampoco ayuda.
Otro aspecto importante para los desarrolladores son las herramientas utilizadas para escribir la documentación. Probablemente sea imprescindible disponer de un sistema compatible con la consola y con editores de texto sencillos.
También hay que tener en cuenta que los pocos proyectos que tienen una documentación excelente pese a disponer de pocos recursos humanos, como PostgreSQL, tienen normas estrictas de redacción y no aceptan un parche sin la documentación correspondiente. Para hacer su seguimiento, la documentación se almacena en el mismo repositorio y se publica junto con el código fuente.
Redactores de documentación
En muchos casos, los desarrolladores serán los redactores de la documentación, pero en esta sección trataremos aspectos que no son necesariamente técnicos ;-)
Algunos problemas de los redactores de documentación son:
- Si el redactor no es el desarrollador que creó el módulo, necesitará una forma de indicar fácilmente que la documentación está vinculada al módulo correspondiente sin tener que modificarlo. Aunque idealmente debería estar vinculada al código del módulo, también necesitan poder documentar módulos sobre los que no tienen control ni permisos de publicación.
- Cuando los redactores no son desarrolladores, necesitan un sistema que puedan utilizar personas no técnicas.
- Crear capturas de pantalla es uno de los peores problemas para mantener actualizada la documentación. Como las vistas varían según los módulos instalados e incluso según el usuario, parece casi imposible disponer de capturas útiles sin invertir un esfuerzo enorme.
- Es complicado mantener actualizados los nombres de los campos y las entradas de menú cuando los desarrolladores los cambian en el código fuente, por lo que también necesitan ayuda en este aspecto.
Traductores
Los traductores sufren problemas similares a los de los redactores, principalmente:
- Mantener actualizadas las capturas de pantalla. Aunque los redactores pudieran crear capturas para todos los casos mencionados, los traductores tendrían que volver a crearlas para su propio idioma.
- Utilizar exactamente las mismas palabras para las entradas de menú y los nombres de los campos que se han utilizado en la traducción de los campos y entradas de menú que ven los usuarios en la aplicación.
- Necesitan un sistema de traducción que les permita hacer un seguimiento fácil de lo que se ha traducido y de lo que todavía no. Tratar una traducción como un único libro que no evoluciona es buscar problemas para el futuro inmediato de los traductores.
