Por una mejor documentación

Echo de menos que a los documentos técnicos no se le aplique el mismo rigor que al código que se desarrolla. Esto ocurre tanto en proyectos donde el negocio es el propio software como en proyectos donde el negocio es otro.

Igual que se usa Excel para todo, se usa siempre Word para mantener la documentación, sea guía de usuario, especificación técnica o normas empresariales. Al trabajar con esta documentación encuentro un montón de problemas:

Que haga falta Microsoft Word para poder ver el documento. Una documentación escrita en HTML se puede leer con cualquier navegador desde cualquier dispositivo.

Que se vean mil estilos diferentes dentro del documento. Con un buen conjunto de estilos predefinidos en CSS se evitaría que un usuario sin querer añada estilos extraños al documento. Además, utilizar características de los preprocesadores como las variables ayudan a que los estilos se diseñen con la precisión milimétrica que un ingeniero debe aplicar.

Que dos documentos de la misma empresa escritos en diferentes épocas tengan diferentes estilos. Un archivo de estilos CSS centralizado para todos los documentos evitaría la necesidad de actualizar los estilos de los documentos porque cambien los colores corporativos de la empresa.

Una tabla poco fiable de historial de versiones dentro del documento. Utilizar un sistema de control de versiones de verdad ayuda a recuperar versiones anteriores del documento y a entender cómo y por qué el documento está evolucionando.

Que los documentos se diseñen para ser imprimidos en lugar de para ser consultados. Una interfaz HTML aporta interactividad para navegar por el documento sin perder la capacidad de que se pueda imprimir teniendo un conjunto de estilos específicos para dicho formato.

Que haya información redundante ya sea porque haya varias definiciones de un mismo concepto o porque el mismo concepto tenga diferentes nombres a lo largo de todo el documento. Ya sabéis que en desarrollo de software, dos métodos que hagan lo mismo es pecado.

Con HTML, cada concepto puede ser un único archivo y cada vez que se nombre ese concepto en la documentación se enlazará a ese archivo (como Wikipedia = MediaWiki con la sintaxis [[]]).

Está claro que no todos los empleados que escriben documentación son técnicos y pueden encontrar dificultad en utilizar un sistema así. Creo que sería labor del departamento técnico educar para que se use un sistema de conocimiento correctamente porque uno de los mayores tesoros de una empresa es el know-how y mantener una documentación pobre y poco fiable no ayuda a nadie.

Anuncios

Responder

Introduce tus datos o haz clic en un icono para iniciar sesión:

Logo de WordPress.com

Estás comentando usando tu cuenta de WordPress.com. Cerrar sesión /  Cambiar )

Google+ photo

Estás comentando usando tu cuenta de Google+. Cerrar sesión /  Cambiar )

Imagen de Twitter

Estás comentando usando tu cuenta de Twitter. Cerrar sesión /  Cambiar )

Foto de Facebook

Estás comentando usando tu cuenta de Facebook. Cerrar sesión /  Cambiar )

Conectando a %s