Christian Arango
Documentation projects

Case study · Multi-product documentation

Priority Commerce SMB documentation system

I designed a multi-product documentation system for Vortex, MXC, MXM, and MXPOS on ReadMe. A shared MDX architecture handles recurring page patterns, while each product loads its own reference package before a draft is transformed. The workflow turns rough source material into review-ready documentation without pretending the four products are identical.

Author
Christian Arango
Role
Technical writer & documentation engineer
Platform
Priority Commerce · ReadMe
Captured
Workflow specification v2.3, October 13, 2026

Project journey

How the work developed

Open each step to follow the problem, the decisions, the build, and what changed as the system matured.

  1. ProblemSupport four products without flattening their differences

    The SMB line shares ReadMe and a recurring set of documentation needs, but each product has its own CSS, JavaScript, HTML, and legacy decisions. The system needed a common foundation without silently applying the wrong product assumptions.

  2. System decisionSeparate the shared MDX contract from product overrides

    I defined one prio-* component architecture for guide bodies, then required the workflow to identify the product and load its reference package before generating anything. Product-specific files win when they conflict with the baseline.

  3. Authoring workflowTurn one discovery pass into review-ready MDX

    The workflow scans for missing titles, URLs, media, numbering problems, and genuinely new structures in one batch. It then generates the page with ReadMe-native components and records only the decisions Christian explicitly deferred.

  4. Trade-offKeep the baseline deliberately simpler

    I did not carry Recurly’s plan pills, TOC bar, or document-type branching into Priority. Priority pages start from one lean guide architecture; new fixed components require a real recurring need and an explicit decision.

  5. ImprovementFold renderer discoveries back into the system

    Table markup, div spacing, image placement, link behavior, and Font Awesome handling became documented guardrails. By version 2.3, all four SMB products had their own reference package and one explicit native-icon policy.

The hard problem

Reuse the architecture, not another company’s documentation system

ReadMe’s renderer constraints are shared; brand voice and product structure are not. I separated platform rules from brand decisions and made product identification the first step, so the workflow never picks components by guesswork.

  1. Scope

    Product detection first

    Every draft is assigned to Vortex, MXC, MXM, or MXPOS before generation; an ambiguous source becomes the first question.

  2. Architecture

    Shared prio-* component contract

    Overviews, callouts, cards, steps, tables, images, code tabs, and accordions share one documented markup vocabulary.

  3. Overrides

    A real reference package per product

    Each package records the CSS, JavaScript, HTML, assets, and deliberate exceptions that override the baseline.

  4. Review

    Human decisions stay visible

    The skill asks once about material gaps, keeps deferred items as TODOs, and produces MDX for review, not autonomous publication.

  • 4 SMB products in scope

  • 4 product reference packages documented

  • 1 shared MDX architecture

Decisions and trade-offs

A smaller shared system was the safer system

The hard choices were boundaries: what belongs to ReadMe, what belongs to Priority, and what stays specific to one product.

  • No speculative components

    A permission badge, version block, or new pattern is added only after a real draft proves the recurring need.

  • No cross-brand inheritance

    Reusable ReadMe behavior can transfer; Recurly’s voice, word bank, and page architecture cannot.

  • Passport stays out of scope

    This system serves the four SMB products and does not silently absorb a separate product line.

  • Product exceptions remain exceptions

    Legacy Vortex, MXM, and MXC choices are recorded instead of “cleaned up” into unapproved behavior changes.

What improved

The workflow became more precise as the product evidence arrived

From a shared baseline with open assumptions to four audit-backed packages and explicit policies.

  • Load context before generating

    Reading the product package first prevents a polished answer built on the wrong interface or styling assumptions.

  • Ask once, then finish the page

    One consolidated discovery pass stays efficient without hiding missing information.

  • Treat renderer quirks as platform knowledge

    Once verified across products, technical constraints become shared guardrails instead of repeated debugging.

This case study documents architecture, decisions, and shipped reference packages. The source provides no measured business outcome, so none is claimed.