Necessitats de documentació dels usuaris i col·laboradors

Probablement coincidirem que la documentació és un dels principals problemes de la majoria de projectes de codi obert, i OpenERP no n’és una excepció. Afortunadament, aquesta regla no sempre es compleix. Alguns projectes, com ara PostgreSQL, tenen una documentació excel·lent, de manera que encara hi ha esperança per als usuaris i els nous desenvolupadors d’OpenERP.

A NaN vam analitzar els problemes que els usuaris, desenvolupadors, redactors de documentació i traductors es troben amb la documentació, i vam intentar resoldre’ls amb un nou mòdul de «documentació» que acabem de publicar. S’integra amb el nostre client Koo, però esperem que la resta de clients i els desenvolupadors de mòduls, especialment OpenERP, s’afegeixin a l’esforç. Per tant, creiem que hem pogut resoldre la majoria de les preocupacions i que ara disposem d’un entorn potent i fàcil d’utilitzar, a l’espera de nous col·laboradors.

En aquest article explicaré quins requisits vam detectar per a cadascun d’aquests grups d’usuaris i col·laboradors, i en un altre article exposaré la solució que vam donar a cadascun.

Usuaris

Els usuaris solen necessitar dos tipus de documentació. D’una banda, volen un llibre que es pugui llegir sense haver de tenir l’aplicació oberta. Un document que es pugui llegir per obtenir una idea general de l’aplicació i de com funcionen i interactuen les coses. D’altra banda, volen ajuda quan la necessiten, és a dir, mentre treballen. Per tant, necessiten una icona que puguin prémer per obtenir ajuda contextual mentre introdueixen informació en un document com ara una factura. En tots dos casos, voldran captures de pantalla que els ajudin a entendre quin aspecte tindran les coses i, sobretot, en quines entrades de menú trobaran allò que estan llegint.

Alhora, els usuaris odiaran haver de saber quins mòduls tenen instal·lats al sistema. Un dels principals problemes de la documentació actual és que OpenERP no pot tenir un únic llibre que expliqui com funciona l’ERP. Això senzillament no té sentit, perquè OpenERP és altament extensible i el comportament pot variar en funció dels mòduls instal·lats. Tradicionalment, les aplicacions han resolt aquesta qüestió amb una llarga llista de «si», que fa que la documentació sigui inutilitzable: «si teniu instal·lat el mòdul X, obtindreu el comportament XX; si teniu instal·lat el mòdul Y, obtindreu el comportament YY; si teniu...». Per tant, és important tenir-ho present: no es pot tenir un document amb la documentació d’OpenERP si no se sap quins mòduls hi ha instal·lats.

Desenvolupadors

Els desenvolupadors odien la documentació, i això és un fet. Dit això, aquesta aversió es pot reduir si coneixem els motius d’aquest sentiment.

Una de les preocupacions és que els usuaris mai no llegeixen la documentació, i probablement hi ha part de veritat en aquesta afirmació. Molts usuaris no llegiran tot el llibre d’OpenERP, però també és cert que utilitzaran l’ajuda proporcionada als camps, per exemple, i això també és documentació. És el que anomenem ajuda contextual, o l’ajuda quan la necessiten.

Una altra preocupació és que escriure documentació d’alguna manera «trenca» el procés de programació. Si no us ho creieu, penseu en els mòduls d’OpenERP. En molts casos, el desenvolupador no va escriure documentació que expliqués què fa el mòdul, però sí que va utilitzar la indicació d’ajuda en diversos camps clau. Sembla, doncs, que aquesta afirmació té part de veritat i que, per tant, mantenir la documentació en un repositori separat i sense enllaçar-la amb les versions i els canvis dels mòduls tampoc no ajuda.

Un altre aspecte important per als desenvolupadors són les eines que s’utilitzen per escriure la documentació. Probablement és imprescindible disposar d’un sistema compatible amb la consola i amb els editors de text senzills.

També cal tenir en compte que els pocs projectes que tenen una documentació excel·lent tot i no disposar de molts recursos humans, com ara PostgreSQL, tenen unes normes estrictes d’escriptura de la documentació i no accepten cap pedaç sense la documentació corresponent. Per fer-ne el seguiment, la documentació s’emmagatzema al mateix repositori i es publica juntament amb el codi font.

Redactors de documentació

En molts casos, els desenvolupadors seran els redactors de la documentació, però en aquesta secció tractarem aspectes que no són necessàriament tècnics ;-)

Alguns dels problemes dels redactors de documentació són:

• Si el redactor de la documentació no és el desenvolupador que ha creat el mòdul, necessitarà una manera d’indicar fàcilment que la documentació que escriu està vinculada amb el mòdul corresponent, sense haver de modificar el mòdul. Encara que, idealment, la documentació hauria d’estar vinculada amb el codi del mateix mòdul, també necessiten poder documentar mòduls sobre els quals no tenen control, és a dir, dels quals no tenen permisos de publicació.
• Quan els redactors de documentació no són desenvolupadors, necessiten un sistema que puguin utilitzar persones no tècniques.
• Crear captures de pantalla és un dels pitjors problemes per mantenir actualitzada la documentació. Si hi afegim el fet que les vistes varien en funció dels mòduls instal·lats i fins i tot per usuari, ja que alguns usuaris poden tenir camps que altres no tenen, sembla gairebé impossible disposar de captures de pantalla útils sense invertir-hi un esforç enorme.
• És complicat mantenir actualitzats els noms dels camps i les entrades de menú a la documentació si els desenvolupadors els canvien al codi font, de manera que també necessiten ajuda en aquest aspecte.

Traductors

Els traductors pateixen problemes similars als dels redactors de documentació, principalment:

• Mantenir actualitzades les captures de pantalla. Sí, encara que els redactors de documentació poguessin crear captures de pantalla per a tots els casos que hem esmentat, els traductors haurien de tornar-les a crear per a la seva pròpia llengua.
• Utilitzar exactament les mateixes paraules per a les entrades de menú i els noms dels camps que s’han utilitzat en la traducció dels camps i les entrades de menú que veuen els usuaris a l’aplicació.
• Necessiten un sistema de traducció que els permeti fer un seguiment fàcil d’allò que s’ha traduït i d’allò que encara no. Fer una traducció com si fos un únic llibre que no evoluciona és buscar problemes per al futur immediat dels traductors.