documentation

Descripción general de la skill de documentación

Qué hace la skill de documentación

La skill documentation te ayuda a crear, reorganizar y revisar contenido técnico usando el modelo Diátaxis: tutoriales, guías prácticas, referencias y explicaciones. Es especialmente útil cuando necesitas algo más que un prompt genérico de redacción y quieres una estructura de documentación que encaje con la intención del usuario.

Quién debería usarla

Usa esta skill de documentación si trabajas en redacción técnica para documentación de producto, documentación de API, flujos de onboarding o documentación interna para desarrolladores. Encaja muy bien cuando ya conoces el tema, pero necesitas ayuda para decidir el tipo de documento adecuado, perfilar el esquema o corregir documentación que confunde a los lectores.

Por qué destaca

Su valor principal es clasificar y estructurar, no solo generar prosa. La instalación de documentation está pensada para ayudarte a separar el contenido de aprendizaje del contenido orientado a tareas, mantener la documentación de referencia en un plano factual y reducir el error habitual de mezclar explicación, procedimiento y detalles de API en una sola página.

Cómo usar la skill de documentación

Instala y abre los archivos correctos

Ejecuta npx skills add mcollina/skills --skill documentation para instalar la skill de documentación. Empieza por SKILL.md y después revisa tile.json para ver el resumen breve y los metadatos. Como este repo no tiene carpetas de apoyo rules/, references/ ni scripts/, el comportamiento principal sale del propio archivo de la skill.

Convierte una petición vaga en un prompt útil

La skill funciona mejor cuando indicas el objetivo del documento, la audiencia y el material de origen. Por ejemplo, en vez de “escribe documentación para mi API”, pide: “Crea una guía práctica para nuevos ingenieros backend que necesitan autenticarse con nuestra API usando una API key; incluye requisitos previos, pasos de configuración, un ejemplo correcto y los casos de fallo más comunes”. Ese tipo de entrada mantiene el uso de documentation enfocado y hace que el resultado sea más fácil de publicar.

Usa primero la decisión de Diátaxis

Antes de pedir contenido, decide si el usuario necesita un tutorial, una guía práctica, una página de referencia o una explicación. Un tutorial enseña haciendo; una guía práctica resuelve una tarea concreta; la referencia documenta hechos; la explicación aclara conceptos y compensaciones. Si te saltas este paso, el resultado puede leerse bien pero aun así no cumplir el estándar de la guía de documentación.

Flujo de trabajo sugerido para obtener mejores resultados

Lee las notas del producto de origen, decide el tipo de documento objetivo y luego pide a la skill que genere un esquema antes del borrador completo si el alcance es amplio. Para documentation orientada a Technical Writing, esto suele dar mejores resultados que pedir directamente una página completa, porque puedes corregir antes el alcance, la terminología y los requisitos previos que falten.

Preguntas frecuentes sobre la skill de documentación

¿Es mejor que un prompt normal?

Sí, cuando la estructura importa. Un prompt normal puede redactar texto, pero la skill de documentación está diseñada para ayudarte primero a elegir el patrón documental adecuado, que muchas veces es el problema real en la redacción técnica.

¿Cuándo no debería usarla?

No la uses para textos de marketing, notas de versión o ensayos de opinión. Tampoco es la mejor opción cuando necesitas una respuesta rápida y única sin contexto de origen, porque el trabajo de documentación suele depender de la audiencia, las restricciones y la tarea que se documenta.

¿Es apta para principiantes?

Sí, siempre que puedas describir el objetivo en lenguaje claro. Quienes empiezan sacan más provecho de la skill de documentación cuando comparten el producto, el nivel del lector y la acción o concepto exacto que quieren documentar.

¿Sirve para documentación para desarrolladores y documentación de API?

Sí. La skill de documentación encaja muy bien con documentación de API, guías de configuración y documentación interna para desarrolladores, especialmente cuando necesitas mantener la referencia separada de tutoriales o guías prácticas.

Cómo mejorar la skill de documentación

Dale a la skill el material bruto adecuado

Los mejores resultados salen de entradas concretas: el nombre del producto, el lector objetivo, el tipo de documento, el estado actual y el resultado exacto que el lector debe lograr. Por ejemplo, “Actualiza nuestra documentación de autenticación para integradores primerizos; tienen que generar un token y probar una solicitud” es mucho más sólido que “mejora nuestra documentación”.

Indica las restricciones desde el principio

Menciona desde el inicio la plataforma, la versión, el tono, la terminología y cualquier limitación de políticas. Si tu instalación de documentation tiene que ajustarse a una guía de estilo existente, a un SDK concreto o a un formato específico del sitio de documentación, dilo antes de generar; de lo contrario, el resultado puede ser estructuralmente correcto pero igual no servir.

Vigila los fallos más comunes

Los problemas más frecuentes son elegir mal el tipo de Diátaxis, mezclar explicación dentro de un procedimiento y escribir contenido de referencia con lenguaje de tutorial. Si el primer borrador queda demasiado amplio, pide que se divida en páginas separadas, que se ajusten más los requisitos previos o que se reescriba para quitar relleno conceptual de los pasos de la tarea.

Itera con ediciones concretas

Después del primer pase, mejora el resultado de la skill de documentación pidiendo un cambio cada vez: “haz que sea una guía práctica pura”, “añade los requisitos previos que faltan”, “convierte los ejemplos al estilo de referencia de API” o “reescribe para usuarios avanzados”. Ese tipo de iteración suele producir una mejor guía de documentación que pedir una revisión general de estilo.