0008 — Transparency-as-product: ADRs and decision-making are user-facing features

• Status: accepted
• Date: 2026-05-06
• Deciders: Derek

Context

Ark’s differentiator vs. Workday / Slack / Squarespace / proprietary CMS isn’t features — those tools have features ark won’t match for years. Ark’s differentiator is that its users understand and own what the platform does.

A consulting agency selling ark to NFP clients sells confidence in business practice — visibility into what data is held, why decisions were made, what’s coming next. The pitch surface and the product surface are the same thing.

Decision

Treat the architecture decision record (ADR) process and operational visibility as user-facing product features, not internal engineering hygiene.

Concretely:

1. The marketing/pitch site for ark is itself a tenant of ark, named ark (slug). It uses ark’s CMS, ark’s themes, ark’s deploy pipeline. No separate marketing infrastructure. The pitch demonstrates the platform by being the platform.

2. ADRs render as public content. docs/decisions/*.md is published (build-time pull) to the ark public site under /architecture/decisions/. Every load-bearing choice ark makes is readable by a non-engineer NFP director.

3. Per-tenant transparency dashboard. Every org admin sees, in their portal:

   • A “What ark stores about us” page summarizing data inventory across the schema
   • An audit log of admin actions (who did what, when)
   • Pending platform updates relevant to their org (linked to the ADRs)
   • A one-click data export (org-scoped)

4. Open changelog. All tenants share the same release notes, generated from accepted ADRs and the migration history. Nothing that affects a tenant is hidden from them.

5. ADR copy quality is a release blocker. An ADR is a product artifact — it should be readable by an org director, not just an engineer. If the ADR reads like internal Slack, it goes back to draft.

Consequences

Easier:

• The pitch deck and the production system co-evolve (no separate marketing rot)
• Users trust the platform because they can see the reasoning
• Internal engineering hygiene (ADRs) is sustained because it’s also the user-facing artifact

Harder:

• ADR writing has a higher quality bar — engineering, but written for non-engineers
• Anything we don’t want users to read shouldn’t be in an ADR; it goes in docs/internal/ (gitignored or private)
• The “ark itself is a tenant” boot sequence has a chicken-and-egg moment we have to solve once

Alternatives considered

• Marketing site separate from the product. Standard pattern; throws away the most credible thing we could show. Rejected — the pitch is the product.
• ADRs internal-only. Forfeits the differentiator. Rejected.
• Public changelog without ADR depth. Marketing release notes; doesn’t validate the “transparency” promise the way actual decision documents do.