{"id":1607,"date":"2026-09-27T05:53:16","date_gmt":"2026-09-27T05:53:16","guid":{"rendered":"https:\/\/blog.juliobrasa.com\/?p=1607"},"modified":"2026-09-27T05:53:16","modified_gmt":"2026-09-27T05:53:16","slug":"documentacion-tecnica-como-crear-la-que-tu-equipo-usara","status":"publish","type":"post","link":"https:\/\/juliobrasa.com\/blog\/documentacion-tecnica-como-crear-la-que-tu-equipo-usara\/","title":{"rendered":"Documentaci\u00f3n t\u00e9cnica: c\u00f3mo crear la que tu equipo usar\u00e1"},"content":{"rendered":"<p><strong>Documentaci\u00f3n t\u00e9cnica<\/strong>: casi todas las empresas dicen que la valoran. Muy pocas la ejecutan bien. En Novalca hemos revisado decenas de equipos de desarrollo y operaciones que acumulan wikis, PDFs y documentos compartidos que nadie abre desde hace meses. Y el problema, casi nunca, es la falta de documentaci\u00f3n. Es que la que existe no responde a las preguntas reales del equipo cuando las tiene. Aqu\u00ed comparto lo que he aprendido creando y depurando documentaci\u00f3n en proyectos de hosting, desarrollo y automatizaci\u00f3n, con ejemplos que puedes aplicar esta misma semana.<\/p>\n<h2>Por qu\u00e9 la documentaci\u00f3n t\u00e9cnica que nadie usa es un problema caro<\/h2>\n<p>La documentaci\u00f3n que no se consulta no es neutra. Es un coste activo. Est\u00e1, primero, el tiempo invertido en escribirla, que puede superar sin problema las decenas de horas por proyecto. Pero el coste de verdad es otro: el que aparece cuando alguien no la usa.<\/p>\n<ul>\n<li><strong>Tiempo de onboarding alargado.<\/strong> Hemos visto incorporaciones que se estiran de dos semanas a dos meses porque el desarrollador nuevo acaba pregunt\u00e1ndolo todo por Slack en vez de encontrarlo documentado.<\/li>\n<li><strong>Conocimiento concentrado en una persona.<\/strong> Cuando solo el t\u00e9cnico senior sabe c\u00f3mo funciona el despliegue del cliente X, cada vacaciones o baja es un riesgo operativo. Nos pas\u00f3 con un proceso de migraci\u00f3n de servidores que viv\u00eda exclusivamente en la cabeza de un compa\u00f1ero durante a\u00f1os.<\/li>\n<li><strong>Errores repetidos.<\/strong> Si el procedimiento correcto no est\u00e1 a mano, cada persona improvisa su propia versi\u00f3n. En entornos de hosting, eso se traduce en configuraciones inconsistentes y tickets de soporte evitables.<\/li>\n<\/ul>\n<p>Haz la cuenta r\u00e1pida. Un equipo de cinco desarrolladores que pierde tres horas semanales buscando informaci\u00f3n que exist\u00eda pero no era localizable: m\u00e1s de 700 horas al a\u00f1o. La documentaci\u00f3n mala no ahorra tiempo. Lo destruye, silenciosamente.<\/p>\n<h2>El error n\u00famero uno: escribir para archivar, no para consultar<\/h2>\n<p>El error m\u00e1s com\u00fan que he visto en todos estos a\u00f1os es escribir documentaci\u00f3n pensando en \u00abdejar constancia\u00bb en lugar de pensar en el momento de uso. Dos mentalidades opuestas:<\/p>\n<ul>\n<li><strong>Documentar para archivar:<\/strong> se escribe al final del proyecto, se describe todo el sistema de forma enciclop\u00e9dica, se usa el punto de vista del que ya lo conoce y se da por terminada en el momento de publicarla.<\/li>\n<li><strong>Documentar para consultar:<\/strong> se escribe pensando en la pregunta concreta que alguien tendr\u00e1 a las tres de la ma\u00f1ana cuando el servidor se caiga. Prioriza lo frecuente sobre lo completo, y se revisa constantemente.<\/li>\n<\/ul>\n<p>Un ejemplo real. Durante a\u00f1os mantuvimos un documento de 40 p\u00e1ginas sobre nuestra infraestructura. Impecable, completo, ordenado. Y pr\u00e1cticamente nadie lo consultaba, porque buscar una respuesta en \u00e9l costaba m\u00e1s que preguntar a un compa\u00f1ero. Lo sustituimos por una p\u00e1gina corta con los diez procedimientos m\u00e1s frecuentes, cada uno resoluble en dos minutos. El uso se dispar\u00f3. La documentaci\u00f3n larga no es mejor documentaci\u00f3n; muchas veces es, directamente, documentaci\u00f3n inaccesible.<\/p>\n<div class=\"result-box\">\n<p><strong>Regla pr\u00e1ctica:<\/strong> si un documento no tiene un lector y una situaci\u00f3n de uso identificables (\u00abel t\u00e9cnico de guardia restaurando una copia de seguridad\u00bb), no est\u00e1 terminado. Est\u00e1 decorado.<\/p>\n<\/div>\n<h2>C\u00f3mo estructurar la documentaci\u00f3n t\u00e9cnica seg\u00fan quien la va a usar<\/h2>\n<p>La segunda causa de documentaci\u00f3n ignorada es la homogeneidad: un mismo formato para lectores distintos. Un desarrollador que integra una API, un t\u00e9cnico de soporte y un empleado reci\u00e9n llegado no necesitan lo mismo, ni de lejos. Antes de escribir una l\u00ednea, identifica para qui\u00e9n es el documento y qu\u00e9 quiere conseguir quien lo abre. En Novalca separamos la documentaci\u00f3n en tres niveles:<\/p>\n<ol>\n<li><strong>Gu\u00edas de referencia (para quien ejecuta):<\/strong> procedimientos paso a paso, comandos exactos, capturas de los estados intermedios. Cero contexto innecesario. Ejemplo: \u00abC\u00f3mo restaurar una copia de seguridad en cPanel\u00bb, con el orden exacto de pasos y qu\u00e9 verificar al final.<\/li>\n<li><strong>Documentos de decisi\u00f3n (para quien mantiene):<\/strong> explican por qu\u00e9 se eligi\u00f3 una arquitectura, qu\u00e9 alternativas se descartaron y qu\u00e9 deudas t\u00e9cnicas se aceptaron. Este nivel es el que casi nadie documenta y, curiosamente, el que m\u00e1s dolores evita seis meses despu\u00e9s.<\/li>\n<li><strong>Onboarding (para quien llega):<\/strong> c\u00f3mo montar el entorno local, d\u00f3nde est\u00e1 cada cosa, a qui\u00e9n preguntar. Corto y orientado a tener algo funcionando el primer d\u00eda.<\/li>\n<\/ol>\n<h3>Una estructura m\u00ednima que funciona<\/h3>\n<p>Para cada documento, usa un esqueleto simple: <em>qu\u00e9 es esto y para qui\u00e9n es<\/em> en las dos primeras l\u00edneas, cu\u00e1ndo usarlo, los pasos o la explicaci\u00f3n y, al final, qu\u00e9 hacer si falla. Ese \u00faltimo apartado, el de fallos comunes, es el que multiplica el valor del documento. La mayor\u00eda de las consultas surgen exactamente ah\u00ed. Y a\u00f1ade siempre una fecha de \u00faltima revisi\u00f3n; un documento sin fecha es un documento en el que nadie conf\u00eda.<\/p>\n<p>Empieza peque\u00f1o. Elige los tres procedimientos que tu equipo consulta con m\u00e1s frecuencia y reescr\u00edbelos con este enfoque. Ver\u00e1s el cambio en la adopci\u00f3n antes de haber documentado ni el 10% de tu sistema.<\/p>\n<h2>Herramientas y formatos que facilitan el consumo (no solo la creaci\u00f3n)<\/h2>\n<p>Hay un fallo cl\u00e1sico aqu\u00ed: elegir la herramienta pensando en quien escribe, no en quien lee. Nos ha pasado. Hemos probado wikis corporativas, Notion, Confluence, Google Docs y hasta un simple repositorio de Markdown. Y la conclusi\u00f3n, tras a\u00f1os, es inc\u00f3moda: la marca del software da casi igual. Lo que importa es si la persona que busca una respuesta la encuentra en menos de 30 segundos.<\/p>\n<p>Cuando digitalizamos procesos en Novalca acabamos valorando tres cosas por encima de cualquier funcionalidad avanzada:<\/p>\n<ul>\n<li><strong>B\u00fasqueda potente:<\/strong> si el motor no encuentra \u00abc\u00f3mo restaurar un backup\u00bb cuando alguien escribe \u00abrecuperar copia\u00bb, la documentaci\u00f3n est\u00e1 muerta. Pru\u00e9bala con las palabras que usa tu equipo, no las que usar\u00edas t\u00fa.<\/li>\n<li><strong>Lectura en m\u00f3vil:<\/strong> muchas consultas t\u00e9cnicas ocurren fuera del escritorio. En el datacenter, de guardia, en un pasillo. Un formato que solo se lee bien en pantalla grande falla justo cuando m\u00e1s se necesita.<\/li>\n<li><strong>Enlaces permanentes por secci\u00f3n:<\/strong> poder compartir el enlace directo al paso 4 de un procedimiento evita capturas de pantalla por Slack y respuestas desactualizadas. Parece un detalle. No lo es.<\/li>\n<\/ul>\n<p>En cuanto al formato, la regla que mejor nos funciona es simple: pasos numerados para procedimientos, estructuras de referencia para cat\u00e1logos (APIs, configuraciones, credenciales de entorno) y diagramas solo cuando el flujo tiene ramificaciones. Un diagrama de una l\u00ednea recta es un documento disfrazado. Y con los v\u00eddeos, cuidado. Son imposibles de buscar y de actualizar. Un v\u00eddeo de diez minutos sin transcripci\u00f3n obliga a quien consulta a verlo entero para localizar un dato de treinta segundos.<\/p>\n<div class=\"result-box\">\n<p><strong>Consejo pr\u00e1ctico:<\/strong> antes de adoptar una herramienta nueva, haz la prueba del becario. P\u00eddele a alguien que no particip\u00f3 en la redacci\u00f3n que resuelva una incidencia real usando solo la documentaci\u00f3n. Cronom\u00e9tralo. Ese tiempo es tu m\u00e9trica real de calidad.<\/p>\n<\/div>\n<h2>C\u00f3mo conseguir que el equipo contribuya y mantenga la documentaci\u00f3n<\/h2>\n<p>Aqu\u00ed mueren la mayor\u00eda de proyectos de documentaci\u00f3n t\u00e9cnica. El documento inicial se escribe con entusiasmo y seis meses despu\u00e9s describe un sistema que ya no existe. Todos lo sabemos. La soluci\u00f3n no es exigir m\u00e1s disciplina, sino reducir la fricci\u00f3n y alinear incentivos.<\/p>\n<p>Tres t\u00e1cticas que nos han funcionado:<\/p>\n<ol>\n<li><strong>Documentar forma parte de la tarea, no una tarea aparte.<\/strong> Si la definici\u00f3n de \u00abhecho\u00bb de un ticket incluye actualizar la p\u00e1gina afectada, la documentaci\u00f3n se mantiene sola. Si se deja \u00abpara despu\u00e9s\u00bb, despu\u00e9s nunca llega. Nunca.<\/li>\n<li><strong>Repartir la propiedad.<\/strong> Cada documento necesita un responsable claro, con nombre y apellidos. La documentaci\u00f3n \u00abde todos\u00bb no es de nadie, y las p\u00e1ginas hu\u00e9rfanas son las primeras que caducan.<\/li>\n<li><strong>Premiar las correcciones, no castigarlas.<\/strong> Cuando alguien edita un documento porque estaba mal, eso es una victoria, no un reproche al autor original. En nuestro equipo, quien corrige una instrucci\u00f3n err\u00f3nea recibe el mismo reconocimiento que quien resuelve la incidencia, porque evit\u00f3 las siguientes veinte.<\/li>\n<\/ol>\n<p>Tambi\u00e9n ayuda dejar constancia de la fecha de revisi\u00f3n en cada documento y programar una revisi\u00f3n trimestral ligera de solo los documentos marcados como cr\u00edticos. Quince minutos al mes por persona. Con eso basta para que el conjunto respire actualidad.<\/p>\n<h2>Conclusi\u00f3n: menos documentos, m\u00e1s respuestas<\/h2>\n<p>La documentaci\u00f3n t\u00e9cnica no es un fin, es un medio. El objetivo nunca fue \u00abtener documentado el sistema\u00bb, sino que cualquier persona del equipo \u2014y tu yo del futuro\u2014 encuentre respuestas r\u00e1pidas sin interrumpir a otros. Cada documento debe medirse por las preguntas que resuelve. No por su extensi\u00f3n ni por su elegancia.<\/p>\n<p>\u00bfPor d\u00f3nde empezar? Por lo que m\u00e1s duele: los tres procedimientos que generan m\u00e1s consultas repetidas. Escr\u00edbelos para quien los va a leer, con formato consumible, un responsable y una fecha de revisi\u00f3n. Luego deja que el uso real te diga qu\u00e9 documentar despu\u00e9s. En pocos meses dejar\u00e1s de responder las mismas preguntas por chat, y tu equipo ganar\u00e1 algo m\u00e1s valioso que cualquier herramienta: autonom\u00eda.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>Documentaci\u00f3n t\u00e9cnica: casi todas las empresas dicen que la valoran. Muy pocas la ejecutan bien. En Novalca hemos revisado decenas de equipos de desarrollo y operaciones que acumulan wikis, PDFs y documentos compartidos que nadie abre desde hace meses. Y el problema, casi nunca, es la falta de documentaci\u00f3n. Es que la que existe no&#8230;<\/p>\n","protected":false},"author":2,"featured_media":1609,"comment_status":"closed","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"rank_math_title":"Documentaci\u00f3n t\u00e9cnica: c\u00f3mo crear la que tu equipo usar\u00e1","rank_math_description":"Aprende a crear documentaci\u00f3n t\u00e9cnica \u00fatil que tu equipo consulte de verdad: estructura, herramientas y errores a evitar. Descubre c\u00f3mo empezarlo hoy.","rank_math_focus_keyword":"documentaci\u00f3n t\u00e9cnica","footnotes":""},"categories":[25],"tags":[],"class_list":["post-1607","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tecnologia-e-ia"],"_links":{"self":[{"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/posts\/1607","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/users\/2"}],"replies":[{"embeddable":true,"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/comments?post=1607"}],"version-history":[{"count":1,"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/posts\/1607\/revisions"}],"predecessor-version":[{"id":1608,"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/posts\/1607\/revisions\/1608"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/media\/1609"}],"wp:attachment":[{"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/media?parent=1607"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/categories?post=1607"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/juliobrasa.com\/blog\/wp-json\/wp\/v2\/tags?post=1607"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}