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, namespace, módulo, CUS, builder, widget, hook, manifest, dashboard.
No uses nombres de otros productos ni analogías del tipo «como en X».
Frontera framework vs plugin¶
Escribe en cortex-docs (docs/plugins/<id>/) | Escribe código en cortex-plugin-* |
|---|---|
| SPI, hooks, activación, CUS genérico | Reglas de negocio, API detallada, eventos de dominio |
Convención operations / admin | Pantallas y flujos propios del plugin |
Índice del grafo (dependency-contracts) | dependencies.md local del plugin |
Puedes citar _template, helloworld o clients como ejemplos de código. No documentes accounting, LangGraph, NIIF ni similares en cortex-docs — enlaza al repo del plugin.
Ver Documentación framework vs plugins y Plugin Developer Handbook.
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»
Verificación¶
Desde cortex-hive:
rg -i 'filament|magento|wordpress|woocommerce|laravel' docs/guias/plugins/
bash docs/scripts/build-pages-staging.sh
Desde cortex-docs aislado: bash scripts/build-pages-staging.sh.
Publicación: Publicar documentación.