Caso de estudio · Documentación multiproducto
Sistema de documentación SMB de Priority Commerce
Diseñé un sistema de documentación multiproducto para Vortex, MXC, MXM y MXPOS en ReadMe. Una arquitectura MDX compartida resuelve los patrones recurrentes de página, mientras cada producto carga su propio paquete de referencia antes de transformar un borrador. El flujo convierte material fuente sin pulir en documentación lista para revisión sin fingir que los cuatro productos son iguales.
- Autor
- Christian Arango
- Rol
- Escritor técnico e ingeniero de documentación
- Plataforma
- Priority Commerce · ReadMe
- Captura
- Especificación del flujo v2.3, 13 de octubre de 2026
Recorrido del proyecto
Cómo evolucionó el trabajo
Abre cada etapa para seguir el problema, las decisiones, la construcción y lo que cambió a medida que maduró el sistema.
ProblemaAtender cuatro productos sin borrar sus diferencias
La línea SMB comparte ReadMe y necesidades recurrentes de documentación, pero cada producto tiene su propio CSS, JavaScript, HTML y decisiones heredadas. El sistema necesitaba una base común sin aplicar en silencio supuestos del producto equivocado.
Decisión de sistemaSeparar el contrato MDX compartido de las excepciones
Definí una arquitectura de componentes prio-* para el cuerpo de las guías y exigí que el flujo identificara el producto y cargara su paquete de referencia antes de generar. Los archivos del producto prevalecen cuando contradicen la base.
Flujo de creaciónConvertir una sola fase de descubrimiento en MDX listo para revisar
El flujo detecta títulos, enlaces o medios faltantes, problemas de numeración y estructuras realmente nuevas en un solo bloque de preguntas. Luego genera la página con componentes nativos de ReadMe y registra únicamente las decisiones que Christian aplazó.
ContrapartidaMantener la base deliberadamente más sencilla
No trasladé a Priority las etiquetas de plan, la barra de contenido ni las ramas por tipo documental de Recurly. Las páginas parten de una sola arquitectura ligera; un componente fijo nuevo exige una necesidad recurrente y una decisión explícita.
MejoraDevolver al sistema lo aprendido del renderer
El marcado de tablas, el espaciado en div, la ubicación de imágenes, el comportamiento de enlaces y Font Awesome se convirtieron en reglas documentadas. En la versión 2.3, los cuatro productos SMB tenían paquete propio y una política explícita de iconos nativos.
El problema complejo
Reutilizar la arquitectura, no el sistema documental de otra empresa
Las restricciones del renderer de ReadMe son compartidas; la voz de marca y la estructura del producto, no. Separé las reglas de plataforma de las decisiones de marca y puse la identificación del producto en primer lugar, para que el flujo nunca elija componentes por conjetura.
- Alcance
Primero se identifica el producto
Cada borrador se asigna a Vortex, MXC, MXM o MXPOS antes de generar; una fuente ambigua se convierte en la primera pregunta.
- Arquitectura
Contrato compartido de componentes prio-*
Resúmenes, callouts, tarjetas, pasos, tablas, imágenes, pestañas de código y acordeones comparten un vocabulario de marcado documentado.
- Excepciones
Un paquete de referencia real por producto
Cada paquete registra CSS, JavaScript, HTML, recursos y excepciones deliberadas que prevalecen sobre la base.
- Revisión
Las decisiones humanas siguen visibles
El skill pregunta una sola vez por vacíos relevantes, conserva lo aplazado como TODO y produce MDX para revisión, no publicación autónoma.
4 productos SMB dentro del alcance
4 paquetes de referencia de producto documentados
1 arquitectura MDX compartida
Decisiones y contrapartidas
Un sistema compartido más pequeño era más seguro
Las decisiones difíciles fueron de límites: qué pertenece a ReadMe, qué a Priority y qué sigue siendo propio de cada producto.
Nada de componentes especulativos
Una etiqueta de permisos, un bloque de versión o un patrón nuevo solo se añade cuando un borrador real demuestra la necesidad.
Nada de herencia entre marcas
El comportamiento reutilizable de ReadMe puede transferirse; la voz, el banco terminológico y la arquitectura de Recurly, no.
Passport queda fuera del alcance
Este sistema atiende los cuatro productos SMB y no absorbe en silencio otra línea de producto.
Las excepciones siguen siendo excepciones
Las decisiones heredadas de Vortex, MXM y MXC quedan registradas en vez de “limpiarse” con cambios no aprobados.
Qué mejoró
El flujo ganó precisión a medida que llegó evidencia de cada producto
De una base compartida con supuestos abiertos a cuatro paquetes respaldados por auditorías y políticas explícitas.
Cargar el contexto antes de generar
Leer primero el paquete del producto evita una respuesta impecable construida sobre supuestos incorrectos de interfaz o estilo.
Preguntar una vez y terminar la página
Una sola fase de descubrimiento mantiene la eficiencia sin esconder información faltante.
Tratar los problemas del renderer como conocimiento de plataforma
Una vez verificados entre productos, los límites técnicos se vuelven reglas compartidas y no depuración repetida.
Este caso documenta arquitectura, decisiones y paquetes de referencia entregados. La fuente no ofrece un resultado empresarial medido, así que no se atribuye ninguno.
Documentación desactualizada
Enlace roto
Guía pendiente