Artículos etiquetados: Modelos de contenido
Sphinx, MkDocs, Astro y otros generadores optimizan modelos de contenido y equipos distintos. Decide por flujo de autoría, extensibilidad, localización y coste de mantenimiento, no por entusiasmo ante una demo. Una demo puede verse excelente y ser incorrecta para tu documentación.
Una estructura que funciona con cincuenta páginas puede fracasar con quinientas. Diseña la navegación alrededor de las tareas del usuario, los tipos de contenido y los conceptos duraderos, no del organigrama. Una colección pequeña puede sobrevivir casi a cualquier navegación.
Una descripción OpenAPI puede generar una referencia precisa, pero los developers siguen necesitando conceptos, flujos, autenticación, ejemplos y recuperación de errores que un schema no puede explicar por sí solo. OpenAPI describe muy bien operaciones, parámetros, estructuras de request y response, status codes y schemas reutilizables.
La consistencia a escala nace de modelos de contenido, terminología y patrones reutilizables, no de pedir que todos memoricen una guía enorme. Codifica las reglas importantes en schemas y componentes. Un equipo pequeño puede apoyarse en hábitos compartidos y edición directa.