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 con systemctl 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 usuario appuser con 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:

1. Copia el proyecto a /var/www/html/app.
2. Edita el archivo de virtual host.
3. Define DocumentRoot /var/www/html/app.
4. Activa el sitio.
5. Reinicia Apache.
6. 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

1. Instala Apache con el comando:

sudo apt install apache2 -y

2. Instala MySQL Server:

sudo apt install mysql-server -y

3. Crea la base de datos proyecto_web:

CREATE DATABASE proyecto_web;

4. Importa el archivo proyecto_web.sql en esa base de datos.
5. Copia los archivos del proyecto a:

/var/www/html/proyecto_web

6. 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

1. Indica qué problemas tiene este texto.
2. Señala al menos 5 aspectos que deberían mejorarse.
3. 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

1. Instala Apache:

sudo apt install apache2 -y

2. Copia la aplicación a la carpeta:

/var/www/html/app_incidencias

3. Crea la base de datos app_incidencias en MySQL.
4. Importa el archivo app_incidencias.sql.
5. Edita el archivo de configuración de la aplicación para introducir:

• nombre de la base de datos
• usuario
• contraseña
• host

6. 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

1. Introducción
2. Objetivo del documento
3. Requisitos previos
4. Instalación del entorno
5. Configuración de la base de datos
6. Despliegue de la aplicación
7. Validación del funcionamiento
8. Problemas frecuentes
9. 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.