¿Qué hace estilo-docs-feishu?
Normas a seguir al escribir documentos de Feishu, aplicables a propuestas técnicas, PRD, retrospectivas e instrucciones. El único objetivo: que alguien lo entienda en una sola lectura.
Cuándo usarlo
Siempre que escribas, modifiques, revises o corrijas un documento de Feishu o un documento técnico, aplica estas normas por defecto, sin esperar a que el usuario las mencione.
Cuando el usuario escriba explícitamente /feishu-doc-style, o pregunte «¿Esto está claro?» o «¿Cómo explico esto mejor?», aplica los cambios siguiendo los «Principios básicos» y la «Lista de verificación antes de entregar».
Al ayudar a alguien a corregir un texto, recorre primero la lista de verificación, identifica las infracciones, proporciona la versión corregida y explica qué cambiaste.
Principios básicos
-
Solo conclusiones, sin razonamiento. Elimina el proceso deductivo de «por qué se eligió esto, cómo se sopesó», da directamente la conclusión. El lector quiere la respuesta, no tu proceso de pensamiento.
-
Párrafos de dos o tres líneas como máximo. Un párrafo no debe superar dos o tres líneas; no acumules muchas oraciones en un solo párrafo largo. Los párrafos largos cansan al leer.
-
Usa diagramas para flujos, no texto. Secuencias, flujos de datos, cambios de estado: exprésalos con diagramas, no con largos bloques de texto. Un diagrama de secuencia vale más que un párrafo extenso.
-
Las flechas solo aparecen en diagramas. Está prohibido escribir cadenas de flechas como «A → B; C → D» en el cuerpo del texto o en tablas. Esto obliga al lector a hacer una búsqueda inversa mental, trasladándole la carga de la interpretación.
-
Habla claro, sin jerga. Los términos internos que el lector no entienda deben traducirse a lenguaje llano, o explicarse con una frase la primera vez que aparecen. Consulta la tabla de jerga común en
references/jargon.md. -
Las celdas de las tablas deben ser oraciones completas y cortas. No pongas abreviaturas técnicas en las celdas; escribe «quién hizo qué y cuál fue el resultado».
-
No uses emojis decorativos ni recuadros de llamada. Emojis como 📌 ⭐ 🔒 💡 ✅ 🚧 y recuadros de llamada de color (callout) hacen que la página se vea desordenada y sucia. Para enfatizar, usa negrita en subtítulos pequeños seguidos de texto normal; para notas a nivel de documento o indicaciones de estado, usa comillas
>. En todo el documento no debe haber ni un emoji decorativo ni un recuadro de llamada. -
Usa la negrita con moderación. Máximo una o dos veces por sección, solo en conclusiones globales reales o en encabezados de principios. No uses negrita en listas de nombres, nombres de campos, palabras direccionales (izquierda/centro/derecha): la jerarquía se expresa con la estructura de oraciones y tablas, no con texto en negrita por todas partes.
-
No uses caracteres que no se puedan escribir con el teclado. Códigos circulares ①②③④⑤, emoticonos de estado ✓ ◐ ◑ ● ○,
!como icono, iconos de función ⚡ ⌘: estos no son caracteres que la gente escriba normalmente; parecen «copiados directamente de la interfaz». Para listas, usa listas ordenadas normales «1. 2. 3.» o «primero, segundo»; para estados, escribe directamente «completado / en curso»; para pasos, usa números normales (Paso 1 / PASO 1). -
Los títulos deben expresar el contenido, no la estructura. El título debe decir directamente de qué trata la sección («Objetivos y métodos principales de este año», «Trabajo en curso y avances»), no incluir lógica organizativa o andamios de escritura. No escribas prefijos estructurales como «Total:» «Parte:» «Primera parte:»: la jerarquía general-particular, paralelismo, secuencia se reflejan naturalmente con el orden del contenido y la jerarquía de títulos. Tampoco añadas metainstrucciones en los títulos (explicaciones sobre el mecanismo como «(AI añade diariamente)» colócalas en el texto normal o en comillas
>). Además, evita encajar contenido en un marco que no le corresponde —por ejemplo, forzar «Varias tareas en curso por área» en una capa temporal como «Avances del primer semestre»; primero piensa en la dimensión organizativa real de ese contenido (estado actual por área, flujo solo por tiempo). Autoevaluación: al leer el título en voz alta, ¿suena como un nombre que una persona normal daría? «Total: objetivos de este año» no suena; «Objetivos de este año» sí suena.
Cómo escribir tablas
Los nombres de las columnas deben estar en lenguaje llano, preferiblemente en forma de pregunta. Por ejemplo, «¿Qué hace el usuario? / ¿Qué hace el sistema en segundo plano? / ¿Hay que esperar en línea?», no uses jerga interna como «Entrada de sincronización / Cadena asíncrona y almacenamiento en base de datos».
Las celdas son oraciones completas y cortas: una frase que explique claramente quién hizo qué y cuál fue el resultado.
Los detalles técnicos van en el cuerpo del texto; la tabla solo sirve para que se entienda. Instrucciones completas de creación de tablas, definiciones de interfaces, etc., colócalas en secciones específicas del texto; no las apiles en la tabla.
Ilustraciones: qué tipo usar para cada caso
Los flujos que se pueden dibujar como diagramas no deben expresarse con texto. Elige el tipo de diagrama según lo que quieras expresar:
| Qué expresar | Tipo de diagrama |
|---|---|
| Flujo lógico, secuencias, cómo fluyen los datos paso a paso | Diagrama de secuencia (mermaid sequenceDiagram), con carriles por rol |
| Cómo se dividen los módulos, quién depende de quién | Diagrama de arquitectura (nodos tipo tarjeta: icono + título + una frase explicativa, coloreado por capa) |
| Cómo fluyen los estados (por ejemplo, de borrador a publicación a retirada) | Diagrama de flujo o diagrama de estados (mermaid flowchart) |
Para saber cómo poner estos diagramas realmente en Feishu (uso de mermaid paint, lark-whiteboard, lark-cli), consulta references/feishu-tooling.md.
Lista de verificación antes de entregar
Antes de entregar, recorre esta lista elemento por elemento. Si algo no se cumple, vuelve a corregir:
- ¿No hay cadenas de flechas (A → B) en el cuerpo del texto ni en tablas? ¿Las flechas solo aparecen en diagramas?
- ¿Cada párrafo tiene como máximo dos o tres líneas?
- ¿No hay jerga sin explicar? ¿La primera vez que aparece un término se da una explicación sencilla?
- ¿Los flujos están expresados con diagramas, no con texto?
- ¿Las celdas de las tablas son oraciones completas? ¿Los nombres de las columnas están en lenguaje llano?
- ¿Se ha eliminado el razonamiento largo de «por qué se eligió esto», dejando solo la conclusión?
- ¿No hay emojis decorativos ni recuadros de llamada de color (callout)? ¿El énfasis se hace con negrita en subtítulos y las notas con comillas
>? - ¿No hay códigos circulares ①②③, emoticonos de estado ✓ ◐, ni otros caracteres que no se puedan escribir con el teclado?
- ¿La negrita es moderada? ¿Máximo una o dos veces por sección para conclusiones globales, sin negrita en listas de nombres / palabras direccionales?
- ¿Los títulos y las tablas no usan palabras en inglés sin traducción? Si hay maquetas en inglés, ¿se ha añadido una paráfrasis en español entre paréntesis?
- ¿Los títulos nombran directamente el contenido, sin prefijos estructurales como «Total: / Parte: / Primera parte:» ni metainstrucciones? ¿No se ha forzado el contenido en una capa temporal inadecuada?
Referencias complementarias
references/jargon.md: Tabla de jerga; las palabras de la izquierda deben cambiarse siempre por las de la derecha (lenguaje llano). Se actualiza continuamente.references/feishu-tooling.md: Notas sobre cómo poner diagramas en Feishu (mermaid paint, lark-whiteboard, lark-cli).
Este skill también sigue estas normas
SKILL.md, README y referencias de este skill están escritos según las normas anteriores. Al modificarlo, primero usa la «Lista de verificación antes de entregar» como autoevaluación: sin emojis decorativos, sin cadenas de flechas, párrafos cortos, títulos con contenido. Si las normas cambian, actualiza simultáneamente SKILL.md y README para que no haya discrepancias.