La documentación tiene un ciclo de vida. Se crea para satisfacer una necesidad, se mantiene para mantenerse precisa a medida que cambian las cosas y, finalmente, se retira cuando la necesidad ya no existe. Tratar la documentación como algo que se escribe una vez y luego se deja intacto es el camino más fiable hacia una base de conocimiento en la que los lectores —y cada vez más, los sistemas de IA que responden en su nombre— dejan de confiar.
Este artículo describe cada fase del ciclo de vida de la documentación y las prácticas que mantienen saludable una base de conocimiento a lo largo del tiempo.
Fase 1: Crear
La creación no comienza cuando abres un documento en blanco, sino cuando identificas una necesidad. Existe una necesidad de documentación cuando los lectores no pueden lograr un objetivo sin ayuda — y esa ayuda aún no existe en tu base de conocimientos.
Identifica qué hay que escribir
Las señales más fiables de lagunas en la documentación son las solicitudes de soporte, la retroalimentación de usuarios y las consultas de búsqueda que no demuestran resultados. Si tu equipo de soporte responde a la misma pregunta diez veces por semana, esa pregunta necesita un artículo. Si los lectores buscan un término que no aparece en tu base de conocimientos, ese término debe estar ahí.
Trata tu cola de soporte como un retraso en la documentación. Cada pregunta que debería haber podido responder con documentación —pero no lo fue— es un vacío que hay que cerrar.
Escribe con un alcance definido
Antes de escribir, define exactamente qué cubrirá y qué no el artículo. Un alcance definido impide que los artículos se expandan indefinidamente y los mantiene centrados en un único objetivo de lector. Escribe el alcance en una frase antes de empezar: "Este artículo explica cómo [tarea] para [audiencia], partiendo desde [estado prerrequisito]."
Si no puedes escribir esa frase con claridad, aún no tienes suficiente claridad sobre lo que estás escribiendo. Aclara primero el alcance.
Revisión antes de publicar
Cada artículo debería ser revisado por al menos otra persona antes de publicarse — idealmente alguien con experiencia en la materia que pueda comprobar la exactitud, y alguien que no esté familiarizado con el tema y que pueda comprobar la claridad. Estos dos críticos detectan diferentes tipos de problemas. Una persona que sea experta y desconozca la perspectiva del lector no sustituye a ambas.
Fase 2: Mantenimiento
El mantenimiento es la fase en la que la mayoría de las bases de conocimiento descuidan y sufren más por descuidado. Una base de conocimiento no mantenida no se mantiene neutral — se degrada activamente. Se leen y se actúan sobre artículos inexactos. Pasos desactualizados llevan a los lectores en la dirección equivocada. Términos que ya no significan lo que antes significaban generan confusión.
Este riesgo ya no se limita a los lectores humanos. Un asistente de IA que cita un artículo obsoleto puede revelar información desactualizada o errónea a alguien que nunca habría encontrado ese artículo por su cuenta mediante búsqueda o navegación — a menudo presentado con la misma confianza que un contenido preciso. Una base de conocimiento poco mantenida no solo pierde silenciosamente la confianza de los lectores que se topan con artículos antiguos; Puede propagar activamente errores por cualquier sistema que lo recupere y resuma.
Crea un calendario de repaso basado en dos variables, no en una sola
Asigna a cada artículo una fecha para reseñar. El intervalo adecuado depende de que dos cosas trabajen juntas, no solo una:
- Con qué frecuencia cambia el contenido subyacente. Los artículos sobre características que cambian rápidamente pueden necesitar revisión trimestral; Los artículos conceptuales fundamentales pueden requerir solo revisión anual.
- Tipo de contenido. Un artículo de referencia (como una API o una lista de parámetros) tiende a quedar obsoleto en el momento en que un sistema subyacente cambia y debe revisarse con el mismo ritmo que el ciclo de lanzamiento de ese sistema. Un artículo conceptual que explique un modelo mental estable puede extenderse con seguridad entre revisiones. Un artículo de resolución de problemas debe revisarse siempre que el síntoma que describe cambie de forma, incluso si la característica subyacente no ha cambiado en papel.
Establece recordatorios de revisión en tu sistema de flujo de trabajo. Cuando llega la fecha de revisión, el propietario del artículo comprueba si el contenido sigue siendo correcto y lo actualiza si no es así. Si es correcto, reinician la fecha de revisión y siguen adelante. Esto lleva minutos para un artículo que no ha cambiado y solo horas cuando se necesitan actualizaciones importantes.
Vincular la documentación con los cambios de producto
La forma más fiable de asegurar que la documentación se mantenga actualizada es hacer que las actualizaciones formen parte del proceso de lanzamiento del producto, y no que sean una ocurrencia secundaria. Cuando una función cambia, la documentación de esa función cambia al mismo tiempo — no semanas después, cuando alguien nota la discrepancia.
Esto requiere una relación entre el equipo de documentación y quien gestiona los lanzamientos de productos. El proceso no tiene por qué ser complejo: basta con un elemento compartido de la lista de verificación que diga "documentación actualizada" antes de que se envíe un lanzamiento.
Responder a los comentarios
El feedback de los lectores —ya sea a través de valoraciones, comentarios o tickets de soporte— es la señal más directa de que un artículo necesita atención. Un artículo que recibe constantemente malas valoraciones o genera preguntas de apoyo de seguimiento te está diciendo algo. Investigarla.
También hay que vigilar las señales más allá de la retroalimentación directa: un aumento en la tasa de búsquedas que llegan a un artículo pero son seguidas inmediatamente por una búsqueda repetida (lo que sugiere que el artículo no respondió a la pregunta), o un cambio notable en la frecuencia con la que un asistente de IA o un motor de búsqueda cita el artículo, pueden indicar un problema de calidad antes de que un solo lector se queje.
No esperes a que se acumulen comentarios. Un solo comentario de un lector que diga "el paso 4 no funciona" es suficiente para que se active una reseña.
Mostrar a los lectores que el artículo se mantiene
Una fecha visible de "última actualización" y, para cambios significativos, una breve nota sobre qué ha cambiado, genera confianza en los lectores de una manera que un artículo invisible no puede. Los lectores (y revisores) están más dispuestos a confiar en un artículo que muestra claramente evidencia de mantenimiento que en uno que no da ninguna señal en ningún sentido.
Fase 3: Jubilación (o consolidación)
La jubilación de la documentación es la parte menos practicada del ciclo de vida, pero importa tanto como la creación y el mantenimiento. Un artículo sobre una función obsoleta, un proceso que ya no existe o una versión de producto que ya no está soportada no es neutral — es engañoso. Los lectores que lo encuentren y sigan se encontrarán con problemas o errores y perderán la confianza en tu documentación en su conjunto. Peor aún, un sistema de IA sin saber que el artículo es obsoleto puede citarlo como hecho actual indefinidamente.
Identificar candidatos para la jubilación
Un artículo es candidato a la jubilación cuando:
- La característica o proceso que describe ya no existe.
- Ha sido reemplazado por un artículo más reciente que trata el mismo tema con mayor precisión.
- La versión del producto a la que se aplica ya no es compatible.
- Recibe constantemente bajas valoraciones y el tema subyacente ya no se aplica.
- Los análisis muestran que recibe casi ningún tráfico y que el tema no es algo que los lectores necesiten.
Saber cuándo consolidar en lugar de jubilarte
No todos los artículos problemáticos deben retirarse de inmediato. Un escenario común son dos artículos que han llegado a tratar el mismo tema —a menudo escritos por personas diferentes en distintos momentos— sin que ninguno esté equivocado. Cuando esto ocurre, la decisión correcta suele ser consolidarlos en un solo artículo autorizado en lugar de eliminar uno y mantener el otro, ya que el artículo superviviente puede estar incompleto. Fusiona el contenido exacto de ambos, retira al perdedor con una redirección al resultado fusionado y apunta la consolidación en el historial de actualizaciones del artículo superviviente.
Jubilaos con elegancia
Retirar un artículo no siempre significa eliminarlo de inmediato. Si el artículo puede seguir siendo relevante para los lectores en versiones anteriores, arquívalo con un aviso claro en la parte superior explicando que el contenido solo se aplica a una versión específica y enlazando a la documentación actual.
Si el artículo es realmente obsoleto, elimínalo y configura una redirección desde su URL al artículo actual más relevante. Un lector que haya guardado un artículo retirado debería encontrar un lugar útil, no por un error 404. Una redirección también impide que un motor de búsqueda o un sistema de IA siga mostrando un enlace muerto mucho después de que el artículo haya desaparecido.
Propiedad y rendición de cuentas
Un ciclo de vida de documentación solo funciona si alguien es responsable de él. Todo artículo debería tener un propietario — una persona responsable de su exactitud y validez. En un equipo pequeño, una persona puede ser la dueña de todo. En un equipo más grande, la propiedad suele distribuirse por área temática o característica del producto.
Documenta la propiedad de forma clara y mantenla actualizada. Cuando la propiedad cambia — porque alguien deja el equipo o la responsabilidad de un área de producto cambia — actualiza los registros de propiedad de la documentación al mismo tiempo. La documentación sin propiedad se convierte en documentación obsoleta.
Planifica para la brecha, no solo para la asignación: cuando el propietario de un artículo se va o se va y aún no se ha nombrado un sucesor, la propiedad debería pasar automáticamente a un respaldo designado — normalmente el líder del equipo o el propietario de la categoría principal — en lugar de quedarse sin asignación hasta que alguien se dé cuenta. Un artículo sin propietario, aunque sea temporalmente, es un artículo que no será revisado.