En el módulo anterior vimos qué es la documentación técnica, por qué es importante y qué tipos de documentación existen en informática.
Ahora toca dar un paso más: entender qué hace que una documentación sea realmente buena.
Porque no basta con documentar.
También hay que documentar bien.
En este módulo el alumno aprenderá cuáles son los principios que convierten un documento técnico en algo útil, claro y profesional. También verá errores muy frecuentes al redactar documentación y aprenderá a detectarlos y corregirlos.
En esta unidad se trabajará:
- claridad
- precisión
- estructura
- consistencia
- legibilidad
- errores comunes al redactar documentos técnicos
¿Qué significa documentar bien?
Documentar bien significa crear un documento que otra persona pueda leer y usar sin perder tiempo, sin interpretar cosas ambiguas y sin tener que preguntarle constantemente al autor.
Una buena documentación técnica debe ayudar a responder preguntas como estas:
- ¿qué es esto?
- ¿para qué sirve?
- ¿cómo se instala?
- ¿cómo se usa?
- ¿qué pasos hay que seguir?
- ¿qué requisitos tiene?
- ¿cómo sé si funciona?
- ¿qué hago si falla?
Si el documento no ayuda a responder este tipo de preguntas, entonces probablemente está incompleto o mal planteado.
Idea clave del módulo
Una documentación técnica no se valora por lo mucho que ocupa, sino por lo útil que resulta.
1. Claridad
La claridad es uno de los pilares más importantes de cualquier documentación técnica.
Un documento claro permite que el lector entienda rápido lo que se le está explicando.
No obliga a releer varias veces una frase ni a deducir lo que el autor quería decir.
Una documentación clara:
- usa frases directas
- evita rodeos innecesarios
- explica cada paso de forma comprensible
- separa bien las ideas
- no mezcla demasiadas cosas en el mismo apartado
Ejemplo poco claro
Aquí habría que configurar el servidor para que funcione correctamente según lo que se necesite.
Ejemplo más claro
Edita el archivo de configuración de Apache y cambia el puerto de escucha a
8080. Después reinicia el servicio consystemctl restart apache2.
En el segundo caso, el lector sabe exactamente qué hacer.
2. Precisión
La claridad no basta si el documento no es preciso.
La precisión consiste en explicar las cosas de forma concreta, exacta y verificable.
Una documentación precisa:
- indica rutas reales
- usa nombres correctos
- menciona versiones cuando importa
- diferencia comandos parecidos
- evita expresiones vagas como “lo normal”, “más o menos”, “si hace falta”, “como siempre”
Ejemplo impreciso
Instala la base de datos y configura el usuario.
Ejemplo preciso
Instala MySQL Server, crea la base de datos
inventario, y después crea el usuarioappusercon permisos sobre esa base de datos.
La segunda versión reduce dudas y mejora la reproducibilidad.
3. Estructura
Muchas veces un documento falla no porque su contenido sea malo, sino porque está mal organizado.
Un texto técnico necesita una estructura lógica.
El lector debe saber dónde empieza una idea, dónde están los pasos, dónde están los requisitos y dónde están los problemas frecuentes.
Una buena estructura suele separar:
- introducción o contexto
- objetivo
- requisitos previos
- pasos a realizar
- validación
- errores frecuentes
- conclusiones o siguientes pasos
Problema muy común
Hay documentación donde se mezclan:
- teoría
- comandos
- capturas
- opiniones
- errores
- resultados
…todo ello sin ningún orden.
Eso hace que el lector tenga que “buscar” la información en lugar de encontrarla de forma natural.
Ejemplo de estructura básica útil
1. Objetivo
Qué se va a hacer.
2. Requisitos previos
Qué hace falta antes de empezar.
3. Procedimiento
Pasos ordenados.
4. Validación
Cómo comprobar que ha salido bien.
5. Problemas frecuentes
Qué errores pueden aparecer.
6. Resultado final
Qué se ha conseguido.
4. Consistencia
La consistencia significa mantener el mismo criterio a lo largo de todo el documento.
Por ejemplo:
- usar siempre los mismos nombres para las mismas cosas
- no cambiar de estilo en cada apartado
- seguir la misma lógica en títulos y subtítulos
- mantener el mismo formato para comandos, rutas, tablas y notas
Ejemplo de falta de consistencia
En una parte del documento escribes:
- Base de datos
- Usuario administrador
- Carpeta del proyecto
Y más adelante escribes:
- BD
- admin
- directorio principal
Aunque no parezca grave, este tipo de cambios genera confusión.
También afecta al formato
Por ejemplo, no conviene que en una parte los comandos estén así:
sudo apt update
y más adelante aparezcan mezclados dentro del texto sin destacar, o que unas rutas lleven formato y otras no.
La consistencia da sensación de orden y profesionalidad.
5. Legibilidad
La legibilidad tiene que ver con lo fácil que resulta leer y recorrer el documento.
No solo importa lo que se dice, sino cómo se presenta.
Mejora la legibilidad:
- usar títulos claros
- crear apartados cortos
- usar listas cuando conviene
- separar bloques de código
- dejar espacio entre secciones
- usar tablas si ayudan a resumir
- destacar notas importantes
- no escribir párrafos gigantescos
Ejemplo de mala legibilidad
Un texto largo, sin subtítulos, con comandos mezclados dentro de frases muy extensas.
Ejemplo de buena legibilidad
Un documento con:
- apartados definidos
- comandos en bloques
- pasos numerados
- advertencias visibles
- ejemplos separados del texto principal
La legibilidad es especialmente importante en documentación técnica porque muchas veces no se lee de principio a fin: se consulta por partes.
6. Orientación al lector
Una documentación técnica no debe escribirse pensando solo en quien la redacta.
Debe escribirse pensando en quien la va a usar.
Eso significa que el documento debe adaptarse al perfil del lector.
No es lo mismo escribir para:
- uno mismo
- un compañero técnico
- un profesor
- un cliente
- un usuario final
Ejemplo
Si documentas una práctica para alumnos principiantes, probablemente debas incluir:
- más contexto
- pasos más detallados
- explicaciones de comandos
- ejemplos visuales
Si documentas para un equipo técnico experto, quizá puedas ser más directo y conciso.
7. Reproducibilidad
Una de las mejores formas de medir la calidad de una documentación técnica es esta:
¿Otra persona podría repetir el proceso con ese documento?
Si la respuesta es no, entonces la documentación no está cumpliendo bien su función.
Para que un documento sea reproducible debe incluir:
- requisitos previos
- pasos en orden
- comandos completos
- rutas correctas
- parámetros importantes
- validación de resultado
- contexto mínimo
Ejemplo
No basta con poner:
Configura Apache para el proyecto.
Eso no es reproducible.
Es mejor algo como:
- Copia el proyecto a
/var/www/html/app. - Edita el archivo de virtual host.
- Define
DocumentRoot /var/www/html/app. - Activa el sitio.
- Reinicia Apache.
- Comprueba el acceso desde el navegador.
8. Mantenibilidad
Una buena documentación no debe servir solo hoy.
También debe poder mantenerse con cierta facilidad.
Una documentación mantenible:
- está bien organizada
- tiene secciones reutilizables
- se puede actualizar sin rehacerla entera
- separa lo estable de lo que cambia mucho
- evita repeticiones innecesarias
Ejemplo
Si una versión del software cambia con frecuencia, conviene que la documentación tenga una sección concreta para versiones o requisitos, en lugar de repartir esa información por todo el documento.
Errores comunes al redactar documentación técnica
Ahora vamos a ver algunos de los errores más frecuentes. Esta parte suele ayudar mucho a los alumnos porque les permite reconocer fallos típicos que ellos mismos cometen al empezar.
Error 1. Dar cosas por supuestas
El autor sabe lo que ha hecho y cree que el lector también lo entenderá.
Ejemplo
Configuramos el servicio como siempre y continuamos con la instalación.
Problema:
¿Como siempre según quién?
Eso solo lo entiende quien lo escribió.
Error 2. Escribir pasos incompletos
A veces se omiten pasos porque parecen obvios.
Ejemplo
Importa la base de datos y ejecuta la aplicación.
Pero quizá falta indicar:
- qué archivo SQL usar
- con qué usuario
- sobre qué base de datos
- en qué orden hacerlo
Error 3. No validar resultados
Muchos alumnos ponen comandos, pero no indican cómo comprobar que funcionó.
Ejemplo
Instala Apache.
Bien, pero falta decir:
- cómo comprobar que está activo
- qué comando usar
- qué respuesta esperar
- qué debería verse en navegador
Error 4. Mezclar demasiadas cosas en el mismo apartado
Por ejemplo, juntar en una misma sección:
- teoría
- comandos
- explicación de errores
- decisiones de diseño
- conclusiones
Esto vuelve la documentación caótica.
Error 5. Usar frases ambiguas
Ejemplos típicos
- “configura lo necesario”
- “haz los cambios correspondientes”
- “instala lo que falte”
- “corrige los errores si aparecen”
Este tipo de redacción parece técnica, pero en realidad aporta muy poca información útil.
Error 6. No adaptar el nivel de detalle
A veces la documentación es tan breve que no sirve.
Otras veces tiene tanto detalle irrelevante que entorpece la lectura.
Hay que encontrar el nivel adecuado según el público y el objetivo.
Error 7. No diferenciar entre borrador y documentación final
Una lista rápida de notas personales no es lo mismo que una guía lista para entregar o compartir.
Es importante enseñar al alumno que documentar también implica revisar, ordenar y pulir.
Cómo mejorar una mala documentación
Una buena forma de enseñar este módulo es mostrar que mejorar documentación no siempre significa reescribir todo desde cero.
Muchas veces basta con aplicar una revisión guiada.
Preguntas de revisión útiles
Antes de dar un documento por bueno, conviene revisar:
- ¿se entiende el objetivo?
- ¿queda claro para quién está escrito?
- ¿los pasos están ordenados?
- ¿faltan requisitos previos?
- ¿hay validación?
- ¿hay frases ambiguas?
- ¿se usan siempre los mismos términos?
- ¿se puede localizar rápido cada parte?
- ¿otra persona podría repetir el proceso?
Ejemplo práctico: de documentación deficiente a documentación útil
Versión deficiente
Instalamos el servidor, cambiamos unas cosas de configuración y luego metemos la base de datos. Después ya se puede probar el proyecto. Si da error habrá que revisar permisos o la conexión.
Versión mejorada
Instalación del entorno
- Instala Apache con el comando:
sudo apt install apache2 -y
- Instala MySQL Server:
sudo apt install mysql-server -y
- Crea la base de datos
proyecto_web:
CREATE DATABASE proyecto_web;
- Importa el archivo
proyecto_web.sqlen esa base de datos. - Copia los archivos del proyecto a:
/var/www/html/proyecto_web
- Comprueba en el navegador que la aplicación responde correctamente.
Validación
- Verifica que Apache esté activo con:
systemctl status apache2
- Comprueba que MySQL esté funcionando:
systemctl status mysql
Aquí ya vemos claridad, estructura, precisión y validación.
Qué debe aprender el alumno en este módulo
Al terminar esta unidad, el alumno debe ser capaz de:
- identificar si una documentación es clara o confusa
- detectar frases ambiguas o imprecisas
- organizar mejor un documento técnico
- aplicar criterios de consistencia y legibilidad
- redactar pasos reproducibles
- revisar una documentación para mejorarla antes de entregarla
Resultado práctico del módulo
El alumno analiza una documentación técnica sencilla, detecta sus fallos y la mejora aplicando principios de claridad, precisión, estructura, consistencia y legibilidad.
Actividad propuesta para el módulo
Actividad: detectar y corregir errores de documentación
Lee este fragmento de documentación:
Se instala el servidor web y luego se configura todo para que funcione con la aplicación. Después se mete la base de datos y se comprueba si va bien. Si falla, revisar lo necesario.
Tareas del alumno
- Indica qué problemas tiene este texto.
- Señala al menos 5 aspectos que deberían mejorarse.
- Reescribe el fragmento para convertirlo en una documentación técnica más útil.
Solución orientativa
Problemas detectados
- no indica qué servidor web se instala
- no explica qué significa “configurar todo”
- no especifica cómo se importa la base de datos
- no incluye rutas ni comandos
- no explica cómo comprobar que funciona
- no concreta qué hacer si falla
Reescritura mejorada
Instalación y configuración básica
- Instala Apache:
sudo apt install apache2 -y
- Copia la aplicación a la carpeta:
/var/www/html/app_incidencias
- Crea la base de datos
app_incidenciasen MySQL. - Importa el archivo
app_incidencias.sql. - Edita el archivo de configuración de la aplicación para introducir:
- nombre de la base de datos
- usuario
- contraseña
- host
- Abre el navegador y accede a la URL del proyecto para comprobar que carga correctamente.
Validación
- comprueba el estado de Apache
- verifica la conexión con MySQL
- revisa permisos de archivos si la aplicación no carga
Caso de uso inventado para este módulo
Imagina que un alumno ha montado una pequeña aplicación de gestión de tareas en PHP y MySQL.
Quiere entregar la práctica, pero su documentación consiste solo en:
- una lista de comandos sueltos
- una captura de la web funcionando
- una frase que dice “la instalación es sencilla”
- una mención rápida a la base de datos
Aunque la aplicación funcione, esa documentación no sería suficiente para:
- repetir el despliegue
- corregir errores
- mantener el proyecto
- evaluarlo correctamente
- entregarlo de forma profesional
El problema no es solo el contenido técnico, sino cómo está explicado.
Ejemplo de índice para un documento bien estructurado
Índice de ejemplo
- Introducción
- Objetivo del documento
- Requisitos previos
- Instalación del entorno
- Configuración de la base de datos
- Despliegue de la aplicación
- Validación del funcionamiento
- Problemas frecuentes
- Conclusión
Este índice ya muestra una secuencia lógica y fácil de seguir.
Ideas clave para recordar
Una buena documentación debe ser clara, precisa y útil.
Si un paso no se puede repetir, la documentación está incompleta.
Escribir mucho no garantiza documentar bien.
Una estructura ordenada facilita muchísimo el trabajo técnico.
La revisión final forma parte de la documentación.
