Guía de estilo de la documentación
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Cómo ubicar una página nueva en la sección correcta, escribirla con el estilo de la casa y superar las comprobaciones de la documentación en el primer push.
Dónde va una página
Una página hace un solo tipo de escritura. Cuando empieza a hacer un segundo tipo, divídela y enlaza.
| Tipo | Responde | Vive en | Voz |
|---|---|---|---|
| Caso de uso | “¿Hace Loom X por mí?” | docs/use-cases/ |
La necesidad se responde en la primera frase; cita un resultado publicado de docs/benchmarks/results.md, con un enlace, cuando existe uno |
| Tutorial | “Muéstrame, de principio a fin.” | docs/getting-started/ |
Pasos numerados que siempre funcionan en el stack por defecto |
| Guía práctica | “¿Cómo logro X?” | docs/guides/, docs/operations/ |
Pasos centrados en el objetivo; asume que se conocen los conceptos |
| Concepto / funcionalidad | “¿Qué es y por qué funciona así?” | docs/concepts/, docs/features/ |
Explicación, compromisos de diseño, enlaces a la referencia |
| Arquitectura | “¿Cómo está construido por dentro?” | docs/architecture/ |
Componentes, flujo de datos, invariantes, rutas de código |
| Referencia | “¿Cuáles son exactamente las opciones?” | docs/reference/ |
Exhaustiva, concisa, preferiblemente generada |
| Benchmark | “¿Qué tan bien funciona y cómo lo sabemos?” | docs/benchmarks/ |
Primero la metodología; números solo con un comando de reproducción |
docs/concepts/explica el modelo que el usuario tiene en la cabeza (identidad, memoria, ranking).docs/features/explica una capacidad desde el lado de quien llama: qué hace, las operaciones, un ejemplo, la configuración, los límites.docs/architecture/explica la misma capacidad desde dentro. Una página de funcionalidad enlaza a ella en lugar de repetirla.docs/development/es solo para contribuidores.
Plantilla de página
Toda página empieza con un título y un párrafo introductorio sencillo: qué cubre la página y qué puede hacer el lector después de leerla. Sin etiquetas como Audience:.
# Retrieval and ranking
`memory.search` combines several retrieval legs into one ranked answer, or abstains when
nothing is close enough. This page explains each leg, how the rank is computed, and
which settings move it.
llms.txt lista la primera oración de ese párrafo para la página, y el sitio de documentación la usa como descripción de búsqueda de la página. Después, donde correspondan: el comportamiento visible para el usuario, las interfaces (operaciones, CLI, ajustes), cómo funciona, límites y modos de fallo, y enlaces a “Related”. Las páginas de arquitectura añaden Source entry points (rutas y símbolos) e Invariants.
Requisitos previos
Cuando una funcionalidad necesita un interruptor del operador o un sistema externo, indícalo en la primera frase de la página: “Needs LOOM_X=true.” Una página de casos de uso es la excepción: su primera frase responde a la necesidad y el interruptor va después. No añadas avisos de madurez ni de estado: enlaza la página de estado generada, que indica si una op es estable y si un interruptor está activado por defecto, y la referencia de operaciones, que recoge de qué depende el listado de MCP.
Reglas de redacción
- El código es la fuente de verdad. Cada configuración, op, campo, make target, ruta y flag de CLI que aparece en una página existe en el árbol. Verifica cada uno.
- Breve. Oraciones cortas, párrafos cortos, tablas para las opciones. Sin metáforas ni marketing.
- Presente, comportamiento actual. Escribe lo que Loom hace. La historia, las fechas y los motivos de un cambio van en el pull request.
- Nombra técnicas, no productos. El texto del repositorio no nombra ningún producto cercano, ninguna persona, ningún host ni espacio de nombres internos, y no cita ningún artículo ni registro de decisión de diseño.
tests/unit/test_public_copy.pyaplica las listas. Compara arquitecturas (“un almacén vectorial separado junto al almacén relacional”), nunca marcas. - Sin adjetivos sin medir. “Rápido”, “escalable”, “preciso” necesitan un número y el comando que lo reproduce, o un mecanismo.
- Explica el porqué. Una decisión de diseño va acompañada del problema que resuelve y de lo que cuesta.
- Enlaza, no repitas. Una página es dueña de cada explicación y de cada tabla; las demás enlazan a su encabezado.
- Sin cifras ni versiones obsoletas. No escribas cuántas ops, configuraciones o tablas existen, ni la versión de un paquete. Enlaza a la referencia generada.
- Los ejemplos funcionan. Los ejemplos de código usan nombres reales del SDK, de la CLI y del protocolo, y funcionan con el stack estándar de la guía de inicio rápido, salvo que indiquen el proveedor o la configuración que necesitan.
Terminología
Usa estas grafías en todas partes; el glosario las define.
| Escribe | No |
|---|---|
operación, op (memory.set) |
endpoint, llamada a la API, herramienta (para la op) |
herramienta MCP (loom_memory_set) |
función |
| espacio de nombres | proyecto, colección, índice |
| tupla de identidad | clave de ámbito |
| plano (plano de memoria, plano de código) | módulo, servicio (para el área del producto) |
memoria, hecho (una fila de loom.memory) |
nota, registro (un registro de un tracker es otra cosa) |
| documento de conocimiento | archivo, carga |
| worker | job, cron (salvo que sea un cron) |
| abstenerse | resultado vacío |
| tombstone | borrado definitivo |
| el dashboard | UI, consola |
| ClickHouse Cloud o ClickHouse OSS | CH (en prosa) |
Formato
- Markdown, formateado con Prettier (
make format; CI ejecutamake format-check). Los bloques de código Python se formatean conruff format, que CI también comprueba. - Encabezados en minúsculas, salvo la primera palabra y los nombres propios. Un solo título
#por página. - Código, nombres de op, ajustes, rutas y nombres de tablas entre acentos graves. Escribe los ajustes como su variable de entorno (
LOOM_CONFLICT_THRESHOLD); las páginas de arquitectura pueden usar el nombre del campo (settings.conflict_threshold). - Las referencias al código fuente son
path/to/file.pymás el símbolo:server/workers/registry.py(_WORKERS). Sin números de línea. - Los diagramas son Mermaid, solo cuando un flujo se entiende mejor dibujado que escrito, y con menos de ~20 nodos.
- Tablas para opciones y comparaciones; prosa para el razonamiento.
- Enlaces relativos entre documentos.
tests/unit/test_doc_links.pycomprueba cada enlace relativo y cada ancla bajodocs/y en los archivos Markdown de la raíz.
Páginas generadas
Estas páginas se generan a partir del código. Edita la fuente y luego ejecuta el generador. make lint ejecuta cada uno con --check, de modo que una página desactualizada hace fallar CI.
| Página | Fuente | Generador |
|---|---|---|
| reference/configuration.md | comentarios sobre los campos en server/settings/ |
python scripts/codegen/settings_reference.py |
| reference/operations.md | server.operations.registry.ALL_OPERATIONS |
python scripts/codegen/docs_reference.py |
llms.txt (raíz del repositorio) |
el título de cada página y la primera frase de su párrafo inicial | python scripts/codegen/docs_reference.py |
reference/operations/<group>.md (uno por grupo) |
los modelos de entrada y salida de las ops y los comentarios sobre sus campos | python scripts/codegen/docs_reference.py |
| reference/workers.md | server/workers/registry.py (_WORKERS) |
python scripts/codegen/docs_reference.py |
| reference/cli.md | la instantánea del analizador de loom tests/unit/snapshots/cli_tree.json |
python scripts/codegen/docs_reference.py |
| reference/errors.md | server/core/errors.py |
python scripts/codegen/docs_reference.py |
| reference/status.md | la maturity de las ops y los ajustes booleanos de server/settings/catalog.py que se cargan como false |
python scripts/codegen/docs_reference.py |
| reference/schema.md | schemas/schema.sql |
python scripts/codegen/docs_reference.py |
En el sitio de documentación, scripts/docs_site/hooks.py sirve la copia en Markdown de cada página junto a la propia página, en su URL más index.html.md y, para el índice de una sección, en <folder>.md, indicada mediante una etiqueta <link rel="alternate" type="text/markdown"> en la página; llms.txt con sus enlaces apuntando a esas copias; llms-full.txt (las páginas que explican qué es Loom y cómo empezar); y el llms-install.md del repositorio.
El sitio publica las páginas generadas desde i18n/<language>/docs/ bajo /<language>/. El inglés es el idioma predeterminado y canónico. Cada página conserva su ruta relativa a docs bajo /<language>/, de modo que la página de inicio y el índice de casos de uso tienen rutas distintas. La página de inicio en inglés enlaza a cada página de inicio traducida disponible, o a su índice de casos de uso traducido cuando la página de inicio no está disponible. Cada página traducida enlaza a su fuente en inglés y a las traducciones equivalentes disponibles. Un aviso marca las traducciones cuyo blob de origen difiere de la página actual en inglés. La generación de traducciones permanece en scripts/i18n/translate.py; la compilación del sitio no llama a ningún proveedor de traducción.
Cuando se elimina una fuente en inglés, sus traducciones marcadas conservan sus rutas hasta que el productor elimine los archivos generados. Estas páginas muestran un aviso de fuente eliminada en lugar de un enlace a la página inexistente en inglés. Los enlaces explícitos de respaldo en inglés conservan su destino en el repositorio porque la página traducida correspondiente puede no contener el ancla solicitada.
Las tablas de ops del SDK (sdk/python/loom/ops.py, sdk/typescript/src/generated/ops.ts) provienen de scripts/codegen/sdk_py_gen.py y sdk_ts_gen.py (generación de código).
Antes de hacer push
make format # Prettier formats the Markdown, ruff its Python blocks
uv run pytest tests/unit/test_doc_links.py tests/unit/test_public_copy.py -q
python scripts/codegen/docs_reference.py --check
pip install --require-hashes --no-deps --only-binary=:all: -r scripts/docs_site/requirements.txt # once, in a virtualenv
mkdocs build --strict # the docs site build CI runs