#Plantillas de página

Cada página del portal es exactamente un tipo. Mezclar tipos es el error más común: una explicación enterrada en un tutorial pierde a quien aprende, y una lista exhaustiva de opciones dentro de un how-to esconde el camino que funciona. Si tu contenido quiere ser dos tipos, escribe dos páginas y enlázalas.

#Cómo elegir el tipo

En una línea: aprender haciendo es un tutorial; resolver una tarea es un how-to; buscar un dato es referencia; preguntar «por qué» es explicación; empezar desde un mensaje de error es troubleshooting.

#Tutorial

Enseñas, y eres responsable de que quien lee llegue al final.

• Abre con el destino: «En este tutorial vamos a…», y muestra el resultado final.
• Un resultado visible después de cada paso.
• Un solo camino: sin opciones, sin alternativas, sin bifurcaciones.
• Explicación mínima; enlaza a la explicación de fondo en vez de incluirla.
• Probado de principio a fin, repetible, sin pasos irreversibles.

#How-to

Quien lee ya es competente y tiene una tarea.

• El título nombra la tarea de forma literal: «Cómo X», nunca «Integrando X».
• Acción y solo acción. Sin enseñar, sin digresiones.
• Ordenado por el flujo de trabajo real.
• No exhaustivo: la lista completa de opciones vive en referencia, enlazada.
• Termina con una sección de verificación: cómo confirmar que funcionó.

#Referencia

Datos para consultar.

• Austera, neutral, factual. Sin instrucciones y sin opiniones.
• La estructura espeja el código o el producto, para que navegar coincida con usar.
• Formato uniforme entre páginas: quien lee encuentra cada cosa en el mismo lugar.
• Los ejemplos ilustran; no enseñan.

#Explicación

Se lee lejos del teclado.

• El porqué: decisiones de diseño, restricciones, historia, trade-offs.
• Las alternativas y los puntos de vista distintos caben aquí, y solo aquí.
• Sin instrucciones paso a paso y sin volcados de referencia.

#Troubleshooting

• El título es el síntoma tal como lo ve quien lee, con el texto exacto del error.
• Una sección por causa distinta.
• Cierra con la verificación de que el arreglo funcionó.

#Reglas que aplican a todos los tipos

• Lo más importante primero: en la página, en cada sección y en cada oración.
• Oraciones cortas, voz activa, presente. «El comando crea el archivo», no «creará».
• Las instrucciones empiezan con un verbo imperativo, y la condición va antes de la acción: «Si usas pnpm, ejecuta…».
• Nunca «simplemente», «solo tienes que», «fácilmente» ni «obviamente».
• Lista numerada para una secuencia; viñetas para un conjunto sin orden; tabla para pares de valores.
• Todo ejemplo de código es real y ejecutable. Sin foo ni bar, sin credenciales reales.
• El texto del enlace nombra su destino. Nunca «aquí» ni «más información».
• Encabezados en minúscula tipo oración, sin punto final, sin saltar niveles.
• Un concepto, un término, en todo el portal.
• Después de un paso importante, muestra la salida esperada: «Deberías ver: …».

#Relacionado

• Cómo contribuir al portal — el flujo completo hasta el MR