Plantilla de documentación técnica en HTML y CSS

Plantilla documentación HTML y CSS con índice lateral adaptable, ejemplos de código, requisitos y pasos de comprobación fáciles de mantener.

Documentar una tarea, no solamente una interfaz

Esta plantilla documentación HTML ofrece un índice, requisitos, un primer recorrido y respuestas a errores frecuentes. Está pensada para una guía pequeña que puedas mantener sin un generador de documentación. El objetivo inicial es que alguien complete una tarea y sepa reconocer el resultado correcto. No basta con enumerar botones o parámetros. Explica qué problema resuelve la herramienta, qué necesita la persona y qué debería observar después de cada paso importante.

Definir a quién va dirigida la guía

Antes de sustituir los textos, decide qué conocimientos puedes dar por supuestos. Una explicación para principiantes necesita aclarar cómo guardar un archivo y dónde comprobar el resultado. Una guía para un equipo experto puede centrarse en configuración y diferencias de versión. Mezclar ambos niveles en cada párrafo hace la lectura lenta. Puedes enlazar a una introducción separada y mantener aquí el recorrido principal. La plantilla proporciona estructura, pero el público determina la profundidad de las instrucciones.

Código completo para probar en tu navegador

Copia este documento en un archivo index.html, guarda los cambios y ábrelo en el navegador. Los nombres y datos de demostración se deben sustituir antes de publicarlo.

<!doctype html>
<html lang="es">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Atlas — Documentación para avanzar</title>
<style>

*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;font-family:Arial,Helvetica,sans-serif;line-height:1.65}button,input,select,textarea{font:inherit}button,a,input{touch-action:manipulation}a{color:inherit}button{cursor:pointer}button:focus-visible,a:focus-visible,input:focus-visible,summary:focus-visible{outline:3px solid currentColor;outline-offset:5px}img,svg{max-width:100%}button{color:inherit}.wrap{width:min(1180px,calc(100% - 48px));margin:auto}.nav{display:flex;align-items:center;justify-content:space-between;gap:20px;padding:24px 0}.links{display:flex;gap:24px;flex-wrap:wrap}.links a{text-decoration:none;font-size:.88rem}.brand{font-weight:900;letter-spacing:-.06em;font-size:1.65rem;text-decoration:none}.eyebrow{font-size:.75rem;font-weight:700;letter-spacing:.15em;text-transform:uppercase}.button{display:inline-flex;align-items:center;justify-content:center;gap:20px;padding:14px 23px;border:1px solid currentColor;text-decoration:none;font-weight:700;border-radius:999px;transition:transform .2s,background .2s}.button:hover{transform:translateY(-3px)}h1,h2,h3,p{margin-top:0}h1,h2{line-height:1.04;letter-spacing:-.055em}h1{font-size:clamp(3rem,7.5vw,6.5rem)}h2{font-size:clamp(2rem,4vw,3.7rem)}h3{line-height:1.2}p{max-width:64ch}.section{padding:88px 0}footer{padding:32px 0;font-size:.8rem}.demo{font-size:.72rem;opacity:.75}details{border-top:1px solid #8885;padding:18px 0}summary{cursor:pointer;font-weight:700}summary+p{margin:16px 0 0}dialog{border:0;border-radius:20px;width:min(760px,calc(100% - 32px));padding:24px}dialog::backdrop{background:#000b}.close{float:right;border:1px solid #8885;border-radius:50%;background:transparent;width:40px;height:40px}section[id]{scroll-margin-top:24px}[hidden]{display:none!important}.reveal{animation:arrive .6s both}@keyframes arrive{from{opacity:0;transform:translateY(16px)}to{opacity:1;transform:translateY(0)}}@media(max-width:700px){.wrap{width:calc(100% - 32px)}.nav{align-items:flex-start}.links{gap:14px}.section{padding:56px 0}h1{font-size:clamp(2.6rem,13vw,4.5rem)}}@media(prefers-reduced-motion:reduce){html{scroll-behavior:auto}*,*::before,*::after{animation:none!important;transition:none!important}}

:root{--bg:#f7f9fc;--surface:#fff;--ink:#1e2e47;--muted:#6e7d92;--line:#dce4ef;--accent:#3d66be;--soft:#eaf0fb}body{background:var(--bg);color:var(--ink)}body[data-dark=true]{--bg:#111a29;--surface:#192538;--ink:#e8eef8;--muted:#a2b1c8;--line:#34445d;--accent:#9cbaff;--soft:#243754}.docs-header{display:flex;align-items:center;gap:20px;padding:20px 32px;border-bottom:1px solid var(--line);background:var(--surface)}.brand{font-size:1.8rem}.brand span{font-size:.8rem;font-weight:400;color:var(--muted);letter-spacing:0}.version{font-size:.6rem;background:var(--soft);border-radius:20px;padding:6px 10px;color:var(--accent)}.docs-header button{margin-left:auto;padding:8px 14px;border:1px solid var(--line);border-radius:7px;background:transparent;font-size:.75rem}.docs-layout{display:grid;grid-template-columns:260px minmax(0,1fr);max-width:1380px;margin:auto}.docs-sidebar{padding:35px 25px;border-right:1px solid var(--line);height:max-content;position:sticky;top:0}.docs-sidebar label{display:block;font-size:.5rem;letter-spacing:.1em;color:var(--muted);font-weight:bold}.docs-sidebar input{width:100%;border:1px solid var(--line);background:var(--surface);color:var(--ink);padding:12px;border-radius:8px;font-size:.75rem;margin-top:12px}.docs-sidebar #search-result{font-size:.6rem;color:var(--muted);margin:9px 0 28px}.docs-sidebar nav{display:grid;gap:7px}.docs-sidebar nav a{padding:10px 12px;border-radius:7px;text-decoration:none;font-size:.75rem;display:flex;gap:10px}.docs-sidebar nav a:hover{background:var(--soft);color:var(--accent)}.docs-sidebar nav span{font-size:.6rem;color:var(--muted)}.sidebar-note{border-top:1px solid var(--line);margin-top:45px;padding-top:25px}.sidebar-note>span{font-size:2.4rem;color:var(--accent)}.sidebar-note p{font-size:.75rem;color:var(--muted);max-width:160px}.docs-main{width:min(850px,100%);padding:50px 65px;min-width:0}.docs-main section{padding:30px 0 50px;border-bottom:1px solid var(--line)}.breadcrumb{font-size:.55rem;letter-spacing:.1em;color:var(--accent)}.docs-main h1{font-size:clamp(3rem,5.5vw,5rem);margin:35px 0 25px}.docs-main h1>span{color:var(--accent)}.lead{color:var(--muted);font-size:1rem;max-width:580px}.intro-cards{display:grid;grid-template-columns:1fr 1fr;gap:15px;margin:35px 0}.intro-cards a{padding:22px;border:1px solid var(--line);border-radius:12px;background:var(--surface);text-decoration:none}.intro-cards b,.intro-cards span{display:block}.intro-cards b{font-size:.85rem}.intro-cards span{color:var(--muted);font-size:.7rem;margin-top:12px}.notice{background:var(--soft);border-left:3px solid var(--accent);padding:18px;font-size:.75rem;color:var(--muted);border-radius:0 8px 8px 0}.notice b{color:var(--ink)}.section-tag{font-size:.55rem;letter-spacing:.1em;color:var(--accent);margin:25px 0 18px}.docs-main h2{font-size:2.1rem;margin-bottom:24px}.docs-main section>p{color:var(--muted);font-size:.85rem}.checklist{list-style:none;padding:0;display:grid;gap:18px;margin:30px 0}.checklist li{position:relative;padding-left:28px}.checklist li:before{content:'✓';position:absolute;left:0;color:var(--accent)}.checklist b,.checklist span{display:block}.checklist b{font-size:.85rem}.checklist span{font-size:.75rem;color:var(--muted);margin-top:5px}.steps{padding-left:22px;margin:30px 0}.steps li{padding:0 0 16px 8px;font-size:.85rem}.steps p{font-size:.75rem;margin:8px 0 0;color:var(--muted)}.code-sample{background:#142137;border:1px solid #34445d;color:#e8eef8;border-radius:12px;overflow:hidden}.code-sample>div{display:flex;justify-content:space-between;align-items:center;padding:12px 18px;border-bottom:1px solid #34445d;font:12px monospace}.code-sample button{background:#2b4164;border:1px solid #52688b;color:#e8eef8;border-radius:5px;padding:5px 10px;font:11px Arial}.code-sample pre{padding:22px 18px;margin:0;overflow:auto;font:12px/1.7 monospace;color:#a9d5ee}.code-sample>p{padding:10px 18px;font-size:.65rem;margin:0;color:#a9b8ce;border-top:1px solid #34445d}.expected{border:1px dashed var(--line);padding:20px;border-radius:10px;margin-top:16px;background:var(--surface)}.expected small{font-size:.5rem;letter-spacing:.1em;color:var(--muted)}.expected p{margin:15px 0 0;font-size:.9rem}.docs-main details{font-size:.85rem;border-color:var(--line)}.docs-main details p{font-size:.8rem;color:var(--muted)}.docs-main footer{font-size:.6rem;color:var(--muted);padding-top:30px}@media(max-width:850px){.docs-layout{grid-template-columns:1fr}.docs-sidebar{position:static;border-right:0;border-bottom:1px solid var(--line);padding:25px}.docs-sidebar nav{grid-template-columns:1fr 1fr;gap:0}.sidebar-note{display:none}.docs-sidebar #search-result{margin-bottom:12px}.docs-main{padding:20px 25px}.docs-header{padding:18px 25px}.docs-header .version{display:none}.intro-cards{grid-template-columns:1fr}}

</style>
</head>
<body>

<header class="docs-header"><a class="brand" href="#inicio">atlas<span> / docs</span></a><span class="version">v1.0 · Demo</span><button id="theme" type="button" aria-pressed="false">Modo oscuro</button></header>
<div class="docs-layout"><aside class="docs-sidebar"><label for="search">ENCUENTRA UNA SECCIÓN</label><input type="search" id="search" placeholder="Buscar en esta guía…" aria-describedby="search-result"><p id="search-result" role="status">4 secciones disponibles</p><nav aria-label="Índice de documentación"><a href="#inicio"><span>01</span> Introducción</a><a href="#requisitos"><span>02</span> Antes de empezar</a><a href="#uso"><span>03</span> Tu primer resultado</a><a href="#problemas"><span>04</span> Si algo no funciona</a></nav><div class="sidebar-note"><span>↗</span><p>Una buena guía te ayuda a dar el siguiente paso.</p></div></aside>
<main class="docs-main"><section id="inicio" data-search="introducción empezar guía documentación"><p class="breadcrumb">DOCUMENTACIÓN / PRIMEROS PASOS</p><h1>Menos dudas.<br><span>Más progreso.</span></h1><p class="lead">Una base clara para explicar tu herramienta, acompañar el primer uso y resolver los problemas que de verdad aparecen.</p><div class="intro-cards"><a href="#uso"><b>Empieza en pequeño</b><span>Un ejemplo mínimo que puedes comprobar →</span></a><a href="#problemas"><b>Encuentra una respuesta</b><span>Síntomas concretos, comprobaciones útiles →</span></a></div><p class="notice"><b>Sobre esta demostración</b><br>Adapta versiones, instrucciones y ejemplos al comportamiento real de tu producto.</p></section>
<section id="requisitos" data-search="requisitos entorno permisos herramientas instalación"><div class="section-tag">01 / PREPARACIÓN</div><h2>Antes de empezar.</h2><p>Enumera condiciones que la persona pueda comprobar antes de seguir el recorrido.</p><ul class="checklist"><li><b>Entorno compatible</b><span>Indica herramientas y versiones verificadas.</span></li><li><b>Permisos necesarios</b><span>Aclara accesos sin publicar credenciales reales.</span></li><li><b>Conocimientos previos</b><span>Enlaza una introducción cuando sea necesaria.</span></li></ul></section>
<section id="uso" data-search="primer uso resultado ejemplo html párrafo código"><div class="section-tag">02 / PRIMER USO</div><h2>Una tarea. Un resultado.</h2><p>Empieza con el ejemplo más pequeño que demuestra una función de tu proyecto.</p><ol class="steps"><li><b>Crea un archivo.</b><p>Guárdalo como <code>index.html</code> en una carpeta de práctica.</p></li><li><b>Introduce el ejemplo.</b><p>Una etiqueta de párrafo es suficiente para comprobar el recorrido inicial.</p></li><li><b>Revisa el resultado.</b><p>Abre el archivo en el navegador y confirma que aparece el texto.</p></li></ol><div class="code-sample"><div><span>index.html</span><button id="copy-example" type="button">Copiar</button></div><pre><code id="example-code">&lt;p&gt;Tu primer resultado visible.&lt;/p&gt;</code></pre><p id="copy-result" role="status">Ejemplo mínimo de HTML.</p></div><div class="expected"><small>RESULTADO ESPERADO</small><p>Tu primer resultado visible.</p></div></section>
<section id="problemas" data-search="problemas error estilos archivo cambios css recursos"><div class="section-tag">03 / DIAGNÓSTICO</div><h2>Si algo no encaja.</h2><details><summary>Veo una versión anterior del archivo</summary><p>Comprueba que guardaste los cambios y que estás abriendo el archivo correcto. No borres datos como primera solución universal.</p></details><details><summary>Los estilos no aparecen</summary><p>Revisa la ruta del CSS y las solicitudes de red que fallan. Distingue un archivo ausente de una regla que no coincide.</p></details><details><summary>Necesito comunicar un error</summary><p>Prepara versión, paso y resultado observado. No envíes contraseñas ni archivos privados.</p></details></section><footer>Atlas / Guía de demostración · Sustituye las instrucciones por información comprobada.</footer></main></div>

<script>

const sections=[...document.querySelectorAll('main section[data-search]')];
document.querySelector('#search').addEventListener('input',e=>{
 const query=e.target.value.trim().toLocaleLowerCase('es');let found=0;
 sections.forEach(section=>{const match=!query||(section.dataset.search+' '+section.textContent).toLocaleLowerCase('es').includes(query);section.hidden=!match;if(match)found++;});
 document.querySelector('#search-result').textContent=found+' secciones disponibles';
});
const theme=document.querySelector('#theme');
theme.addEventListener('click',()=>{const dark=document.body.dataset.dark!=='true';document.body.dataset.dark=String(dark);theme.setAttribute('aria-pressed',String(dark));theme.textContent=dark?'Modo claro':'Modo oscuro';});
document.querySelector('#copy-example').addEventListener('click',async()=>{try{await navigator.clipboard.writeText(document.querySelector('#example-code').textContent);document.querySelector('#copy-result').textContent='Ejemplo copiado.';}catch{document.querySelector('#copy-result').textContent='Selecciona el código y usa Copiar.';}});

</script>
</body>
</html>

Requisitos que se puedan comprobar

Enumera entorno, versiones, permisos y herramientas cuando sean relevantes. Evita expresiones como Usa una versión reciente si una función requiere una condición concreta. Indica cómo verificar el requisito y qué hacer cuando no se cumple. No incluyas claves reales, contraseñas ni credenciales en ejemplos. Para configuraciones sensibles utiliza valores de demostración identificados como tales y explica dónde debe colocar el usuario sus propios datos. Los requisitos correctos reducen errores antes de empezar.

Un ejemplo mínimo con resultado esperado

El bloque de código muestra un párrafo porque permite separar estructura y contenido. Sustitúyelo por el ejemplo más pequeño que demuestre una función real de tu proyecto. Después describe el resultado observable: texto, archivo creado o respuesta concreta. Si el usuario solamente ve una orden sin saber qué debe ocurrir, no puede distinguir éxito de fallo silencioso. Cuando el ejemplo necesite varios archivos, presenta sus nombres y relaciones en un orden que pueda reproducirse.

Código visible sin ejecutarlo como contenido

Dentro de pre y code, los caracteres que forman etiquetas deben escaparse para que el navegador los muestre en lugar de interpretarlos. El ejemplo utiliza entidades para los signos de apertura y cierre. Cuando copies fragmentos de una aplicación, revisa que no queden datos privados. No incrustes scripts de muestra como código activo dentro de la documentación. Una explicación técnica debería permitir leer el ejemplo sin que éste altere la propia página o ejecute acciones inesperadas.

Un índice lateral que se adapta

En escritorio, el índice ocupa una columna y permanece cerca del borde superior mientras se recorre la guía. En pantallas estrechas pasa al flujo normal para no comprimir el contenido. minmax y min-width permiten que los bloques de código se desplacen dentro de su espacio sin ensanchar toda la página. Los enlaces apuntan a identificadores únicos. Si cambias un encabezado, puedes conservar su identificador para no romper enlaces compartidos anteriormente.

Errores frecuentes con pistas de diagnóstico

Cada respuesta debería partir de un síntoma reconocible y proponer una comprobación concreta. Revisa la configuración es demasiado impreciso si no explicas dónde mirar. El ejemplo distingue archivo antiguo y estilos ausentes porque requieren verificaciones diferentes. No recomiendes borrar todos los datos o reinstalar herramientas como primer paso universal. Empieza por acciones pequeñas y observables que ayuden a localizar la causa. Cuando un problema excede el alcance de la guía, indica qué información necesita soporte para investigarlo.

Mantener versiones y enlaces útiles

Añade la versión o fecha de revisión que tenga sentido para tu proyecto y actualízala cuando cambien las instrucciones. Prueba los ejemplos desde un entorno limpio antes de publicar una revisión importante. Comprueba cada enlace del índice y el recorrido con teclado. Si el contenido crece en varios productos o versiones, puede ser momento de usar un sistema especializado. Esta plantilla funciona mejor como una base clara y pequeña, con instrucciones comprobadas y un mantenimiento que el equipo pueda sostener.

Distinguir explicación, referencia y solución de problemas

Una introducción enseña el contexto, un tutorial guía una tarea y una referencia permite consultar opciones concretas. Puedes combinarlos en una documentación pequeña, pero conviene etiquetar su función. No interrumpas cada paso del primer uso con todas las alternativas posibles. Lleva esas variantes a un apartado de referencia o a enlaces posteriores. El usuario que empieza necesita un recorrido que termine; quien ya conoce la herramienta necesita localizar un dato. Una estructura consciente permite servir a ambos sin convertir cada página en una mezcla difícil de recorrer.

Mantener ejemplos que puedan ejecutarse

Cuando cambie la herramienta, prueba los fragmentos publicados y revisa sus resultados esperados. Un ejemplo que se queda antiguo puede parecer un error del usuario. Si depende de una versión, indícala junto al contexto de uso. Mantén separados valores de demostración y configuración real. Cuando una instrucción modifica o borra datos, explica su efecto antes del paso y ofrece un entorno de práctica apropiado. La utilidad de la documentación depende de que las instrucciones sigan describiendo lo que hace el producto actual.

Enlaces estables y documentación que se pueda citar

Los identificadores de los apartados permiten compartir una respuesta concreta. Evita cambiarlos solamente para que coincidan con un nuevo título si eso rompe enlaces que el equipo ya utiliza. Si reorganizas páginas, prepara redirecciones o conserva anclas compatibles cuando sea razonable. Los nombres deben ser únicos y descriptivos. Comprueba también que un encabezado alcanzado mediante enlace no quede escondido bajo una cabecera fija. Una documentación fácil de citar reduce mensajes repetidos y permite responder dudas enviando a una explicación mantenida, en lugar de copiar instrucciones distintas en cada conversación.

Invitar a comunicar un error con contexto

Puedes añadir un canal para señalar instrucciones que no funcionan. Pide versión, paso y resultado observado, evitando solicitar credenciales o archivos privados. Esa información permite reproducir el problema y corregir la guía. Si recibes la misma duda varias veces, revisa el apartado antes de crear otra respuesta aislada. Un documento mantenido acumula aclaraciones donde serán útiles para la próxima persona. La plantilla no necesita un sistema complejo de comentarios para empezar; un contacto claro y una rutina de revisión pueden ser suficientes para convertir incidencias reales en mejores instrucciones.

Guías relacionadas para seguir practicando

Puedes ampliar esta práctica con Entender el posicionamiento CSS y Diagnosticar recursos que fallan.