Se ha hablado mucho sobre la escasez de documentación en proyectos libres, tanto de manuales técnicos o de administración, que expliquen como instalar y administrar el software, como manuales de usuario, que expliquen cómo realizar las actividades que propone el software realizar.
Es claro que, cuando una persona aprende a desarrollar, a programar, se sienta frente al ordenador y comienza esa frenética batida de golpes contra el teclado, una pausa para ver los resultados, un momento de pensar en el siguiente paso, y otra vez a teclear... en esos momentos, la documentación, si se piensa hacer, es algo que se estima para un futuro... para cuando se dé a conocer.
Es lógico que un proyecto grande, creado con una línea en mente, a veces por una empresa o una entidad como puede ser una fundación o una universidad, suele ser otra cosa (casos como MySQL, PHP, PostgreSQL, Firefox, OpenOffice, Apache, ...).
La documentación es como la lluvia, nunca cae a gusto de todos, por lo que es muy complicado realizar un documento sobre un programa que cumpla con las expectativas de todos los posibles usuarios que vaya a tener el programa.
Los tipos de documentación que se han identificado a lo largo de los años pueden englobarse dentro de los siguientes grupos:
- Receta (o How-To): es un documento para gente que quiere hacer algo funcionar de forma rápida y no se quiere parar en detalles. Suelen ser documentos cortos, concisos y estructurados en pasos.
- Getting Started: algo así como los primeros pasos. Es para gente que quiere ver algo funcionar de forma rápida, para después centrarse en los detalles. Es básicamente en lo que se fundamenta Linux, Unix y demás sistemas parecidos... la filosofía Unix.
- Manual: suele ser un libro extenso donde se explican, por capítulos, cada parte específica del programa. Este tipo de documento suele venir bien para quien tiene interés en aprender a usar bien el programa y, depende del enfoque, el modo en que se use: usuario, administrador, instalación...
- Tutorial: parecido al anterior, pero más pedagógico, intenta adentrar de una forma más suave al usuario a lo que es el uso del programa.
- White Paper: La idea de fondo que mueve la creación de herramientas y soluciones. No tiene en mente una implementación concreta solo promueve una idea, casos de uso, formas de posible implementación, especificaciones a cumplir y toda la información para permitir construirlo.
- Guía de Referencia: suelen ser los comandos o atajos que se pueden usar en cada parte del programa, ya sean comandos, teclas rápidas, combinaciones, menús de acceso... depende de cómo se presente el programa.
Hay proyectos, comerciales y libres, que reúnen toda esta variedad de documentos, lo cual es muy útil y, aún así, sigue habiendo problemas entre los usuarios, puesto que la calidad u orientación de los mismos, puede no ser muy precisa o atinada. En este aspecto, los manuales, en su mayoría, suelen tener un baremo en el que presentan el público a quien va dirigido el documento y lo que trata en sí, encontrándose así libros para gente nueva en el tema, de nivel bajo, intermedio o avanzado.
En proyectos de gran tamaño, como puede ser Apache, la documentación que se reúne, puede sobrepasar, perfectamente, las mil páginas. Más en concreto, el manual de usuario con guía de referencia de PHP (de su página web) tiene un tamaño de aproximadamente 2000 páginas.
Por lo tanto, no es que los programadores o desarrolladores no hagan documentación... es que escribir documentación es una tarea ardua, larga y conlleva más tiempo que en escribir el código del programa que se documenta para, después, encima, ver que la documentación escrita no es suficiente, o no se entiende bien... ya que, además, si la escribo en castellano, no es lo mismo que si la escribo en inglés, por supuesto.
