Lewati ke konten utama

Documentation Guidelines

Writing standards for Kesles Merchant docs. Used by every team (backend, mobile, dashboard, ops, product) to keep docs consistent, easy to find, and leak-free.

merchant_docs/ folder structure​

There are two tiers of docs, with different deploy targets:

merchant_docs/
├── README.md                              ← top-level index
│
├── api_docs/                              ← Docusaurus sites (deployed)
│   ├── internal/                          ← internal site → internal-docs-merchant.kesles.com
│   │   ├── docs/
│   │   │   ├── dev/                       ← dev docs plugin
│   │   │   │   ├── intro.md
│   │   │   │   ├── runbooks/              ← deploy, incident, secret rotation, master-key rotation, partner-access-setup
│   │   │   │   ├── api-internal/          ← internal API contracts (partner, mobile, dashboard-admin)
│   │   │   │   ├── architecture/          ← system design, topology, partner-access-scope, db-schema, etc.
│   │   │   │   ├── business-formulas/     ← confidential IP: profit/price/margin, qrisplus strategy
│   │   │   │   ├── operations/            ← SOPs (purchase-invoice-types)
│   │   │   │   ├── development/           ← shipping-device DB ref, KTP OCR, registration flow
│   │   │   │   ├── apps/                  ← per-app docs
│   │   │   │   ├── services/              ← per-service docs
│   │   │   │   ├── database/              ← DB schema reference
│   │   │   │   └── meta/                  ← this file
│   │   │   └── psp/                       ← PSP docs plugin (events, integration, reference, testing)
│   │   ├── i18n/id/                       ← Bahasa Indonesia translations (Docusaurus i18n)
│   │   └── static/postman/                ← Postman collections + environments
│   └── public/                            ← public site (partner / merchant audience)
│
└── docs/                                  ← internal working notes (NOT deployed)
    ├── architecture/                      ← approved plans engineering yang tidak perlu di Docusaurus
    ├── development/                       ← checklist & plan proses development (quickstart, MVP spec, IoR, dll)
    ├── operations/                        ← engineering roadmap & operasional internal
    ├── plans/                             ← draft plans (belum approved)
    ├── planning/                          ← alignment notes, decision log
    ├── secrets/                           ← pointer ke credential aktif (TIDAK menyimpan plaintext)
    └── i18n/id/                           ← terjemahan ID mirror untuk architecture/development/operations

Classification Rules​

Before writing a new document, ask:

  1. Is this an API contract / PSP integration? → api_docs/internal/docs/dev/api-internal/ (NDA-locked) — atau api_docs/public/ kalau partner external.
  2. Does this reveal commercial formula / pricing strategy? → api_docs/internal/docs/dev/business-formulas/ (internal Docusaurus, NDA via Cloudflare Access).
  3. Is this an operational runbook (deploy, backup, restore, incident, rotation)? → api_docs/internal/docs/dev/runbooks/.
  4. Is this an SOP (role access, purchase invoice types)? → api_docs/internal/docs/dev/operations/.
  5. Is this system design / topology / approved architecture plan?
    • Butuh ter-publish di Docusaurus internal? → api_docs/internal/docs/dev/architecture/.
    • Cukup internal working note tanpa publish? → docs/architecture/.
  6. Is this a dev note / setup checklist / refactor plan?
    • Operasional yang perlu di-publish (DB ref migration, registration flow, KTP OCR)? → api_docs/internal/docs/dev/development/.
    • Working notes yang tidak perlu di-publish (quickstart, MVP spec, IoR playbook)? → docs/development/.
  7. Is this a draft plan masih in-review? → docs/plans/. Pindah saat approved.
  8. Is this safe to publish to partners / the public? → api_docs/public/docs/.

If multiple categories overlap, default to the most restrictive folder (e.g. payment + API → api-internal/ with PSP role attribution, not public/).

Naming Convention​

  • Lowercase kebab-case: partner-api-reference.md, not PartnerAPI.md
  • Document-type suffix when useful: -plan.md, -spec.md, -checklist.md, -runbook.md, -sop.md, -contract.md
  • For versioned docs: -v1, -v2 at the end. Do not put dates in the filename (use git history)

Document Structure​

Every markdown file should at minimum have:

# Document Title

## Purpose / Context
(1-3 paragraphs: why this doc exists, who it's for)

## Main Content
(sections per topic)

## Status / Last Updated
(optional: for plans / proposals still in flux)

Within Docusaurus (api_docs/internal/docs/ or api_docs/public/docs/) — use relative paths between files, Docusaurus resolves at build time:

[Service Topology](../architecture/service-topology.md)

From Docusaurus to working notes (merchant_docs/docs/...) — target is outside Docusaurus build, so a markdown link will break the build. Reference as plain text + full path:

See `merchant_docs/docs/architecture/repo-strategy.md`.

Within working notes (merchant_docs/docs/) — use relative paths between sibling files:

[Reports Plan](../architecture/reports-plan.md)
  • For files outside merchant_docs/ (e.g. source code), reference with backticks + path-from-repo-root, e.g. `services/dashboard_api/internal/app/handler.go`.
  • Do not use absolute filesystem URLs like /Users/... — they're not portable.
  • Do not use shorthand merchant_docs/architecture/X.md (folder tidak ada) — pakai path penuh merchant_docs/docs/architecture/X.md atau merchant_docs/api_docs/internal/docs/dev/architecture/X.md sesuai lokasi.

Language​

  • Default: English for all docs in this site (internal & public).
  • Indonesian translations live in i18n/id/ and are managed via Docusaurus i18n.
  • Mixed-language is fine when a technical term has no good translation (endpoint, token, webhook, etc.).

Secret Hygiene​

  1. Never commit real credentials / secrets — use placeholders ({{jwt_token}}, {{hmac_secret}}).
  2. Never screenshot real production merchant data — blur it or use dummy data.
  3. When in doubt about whether a doc can be committed, put it in api_docs/internal/docs/dev/business-formulas/ (NDA-locked internal site) atau di docs/secrets/ (pointer only, no plaintext) dan request review.

Review​

  • Changes to internal Docusaurus (api_docs/internal/docs/) yang non-confidential → regular PR, 1 approver.
  • Changes to dev/business-formulas/ atau dev/api-internal/ (PSP/HMAC) → PR + tech-lead approval.
  • Changes to api_docs/public/ → PR + tech-lead and marketing approval.
  • Changes to merchant_docs/docs/ (working notes, tidak di-deploy) → regular PR, 1 approver.

Tooling​

  • Markdown preview: VSCode built-in or Typora
  • Diagrams: Mermaid embedded directly in markdown, not separate PNGs
  • OpenAPI: store YAML next to its consumer (e.g. api_docs/internal/docs/dev/api-internal/), generate HTML docs at release time
  • Postman collections + environments: simpan di api_docs/internal/static/postman/ (served oleh Docusaurus sebagai static asset)