Estilo y voz¶
Guía para quien escribe o revisa la documentación de plugins en docs/guias/plugins/.
A quién hablamos¶
Al desarrollador que construye plugins: usuario del producto, no del framework interno. Asume conocimiento de Python y FastAPI, no del monorepo completo.
Principios¶
| Principio | En la práctica |
|---|---|
| Empatía | Anticipa el esfuerzo de migrar o activar un plugin. Indica qué rompe y qué no. |
| Una idea por página | Fragmenta temas grandes. Cada título debe explicarse solo. |
| Qué y por qué | Abre con propósito; el cómo va en snippets y pasos numerados. |
| Imperativo | «Crea», «Registra», «Activa». |
| Honestidad | Nombra APIs inestables y patrones legacy sin suavizar. |
| Depreciación visible | !!! warning "Deprecado" + alternativa recomendada. |
Estabilidad del contenido¶
| Etiqueta | Significado |
|---|---|
| Implementado | Contrato estable; hay plugin de referencia en el repo. |
| Beta | Funciona; la API puede cambiar. Probar antes de producción. |
| Diseño | SPI o infra listos; sin ejemplo en plugins aún. |
| Deprecado | Sigue funcionando; no usar en plugins nuevos. |
Usa admoniciones MkDocs cuando no sea Implementado.
Vocabulario¶
Usa términos Cortex: Resource, Panel, módulo, CUS, builder, widget, tenant, hook, manifest, dashboard.
No uses nombres de otros productos ni analogías del tipo «como en X».
Evita¶
- «Obviamente», «simplemente», «fácilmente»
- Párrafos largos sin subtítulo
- «Próximamente…» sin etiqueta Diseño o enlace a ADR
Plantilla por página¶
- Frase de valor
- Cuándo aplica (viñetas)
- Ejemplo mínimo (código del repo)
- Referencia API
- Contrato HTTP (si aplica)
- Errores frecuentes (opcional)
- Un enlace «Siguiente paso»