Writing philosophy

Good technical writing is not about following rules — it's about removing obstacles between a reader and the information they need. These are the principles that shaped every page in this portfolio.

MSTP compliance — what it actually means

The Microsoft Writing Style Guide is the de facto standard for developer-facing documentation across the technology industry. But "MSTP compliant" is often used as a checkbox. In practice, it means making dozens of micro-decisions on every page that collectively reduce the cognitive load on the reader.

Active voice

Active voice identifies who does what. Passive voice obscures agency — which is especially damaging in compliance, error, and troubleshooting documentation where readers need to know exactly who or what is responsible for an action. 

The request is authenticated by supplying
an API key in the Authorization header.

A 401 error is returned when the key
is missing or has been revoked.

Cases can be created by calling the
/cases endpoint.
Authenticate requests by including your
API key in the Authorization header.

The API returns a 401 error when your
key is missing or revoked.

To create a case, call the /cases
endpoint.

Second person ("you")

Second person makes developer documentation feel like a direct conversation rather than a technical report. It also forces specificity: "you must supply an API key" leaves no ambiguity about who is responsible. "One must supply an API key" or "the developer must supply an API key" introduces unnecessary formality that slows reading.

Sentence-case headings

Title case is a legacy convention from print publishing. In digital developer documentation, sentence case (capitalise only the first word and proper nouns) is easier to scan, easier to translate, and reduces the visual noise that makes documentation feel bureaucratic. Every heading in this portfolio uses sentence case.

No minimizers

Words like "simply," "just," "easy," "straightforward," and "obviously" are dangerous in technical documentation. They are condescending when the reader is struggling, and they set an expectation of ease that makes readers feel incompetent when things go wrong. Remove them without replacement. 

Simply call the /cases endpoint. 
It's easy to set up authentication —
just pass your API key in the header.
Obviously you'll need to create an
account first.
Call the /cases endpoint.
To authenticate, pass your API key
in the Authorization header.
Before you begin, create a CaseForge
account at app.caseforge.io/signup.

Present tense

Documentation describes a system's current behavior, not a future prediction. Present tense ("the API returns") is more accurate and less wordy than future tense ("the API will return"). The exception is migration guides, where future tense is appropriate to describe what a version will change.

Documenting failure states

The most read sections of any API or SDK reference are error handling and troubleshooting. Developers consult them when something has gone wrong — which means they are already under pressure. This is where documentation quality has the highest real-world impact.

Error tables that actually help

A generic HTTP status table ("400 — Bad Request. 401 — Unauthorized.") tells a developer nothing they don't already know. Useful error documentation:

  • Maps the platform's specific error codes (not just HTTP status codes) to root causes
  • Tells the reader what action to take, not just what went wrong
  • Distinguishes errors the developer caused from errors the system caused
  • Identifies which errors are retryable and which require human intervention

Example from CaseForge SDK error-handling page

See how the error-handling guide maps Python exception classes to HTTP status codes, groups errors by root cause, and provides explicit retry guidance with configurable backoff parameters.

Exception hierarchies

SDK documentation should explain the exception class hierarchy, not just list error codes. When a developer catches CaseForgeAPIError, they need to know whether AuthenticationError and RateLimitError are subclasses of it — otherwise they can't write correct exception handling. This is rarely documented, and its absence forces developers to read source code.

Idempotency and retry semantics

Financial and compliance APIs carry real-world consequences for duplicate operations. Documenting when to retry (network errors, 503s), when not to retry (401, 400), and how idempotency keys prevent duplicate effects is not optional — it's the difference between a developer building a safe integration and one that occasionally duplicates transactions or case submissions.

Plain language in high-stakes domains

FinTech, AML, and compliance documentation carries a temptation toward defensive complexity: long sentences full of qualifications, passive constructions that obscure accountability, jargon that signals domain expertise. These patterns make documentation harder to use and more likely to produce errors in implementation.

Domain terms vs. jargon

There is an important distinction between domain terms (which are precise and necessary) and jargon (which is imprecise and exclusionary). AML, SAR, NACHA, OFAC, and ISO 20022 are domain terms — they name specific regulatory frameworks and organizations, and substituting plain-English descriptions would be both longer and less accurate. "Flags the transaction for review" instead of "triggers a suspicious activity alert" is jargon.

Defining terms once, explicitly

Every domain-specific term should be defined at first use with a glossary entry or inline definition, and then used consistently thereafter. In AML documentation, "case" has a specific legal meaning distinct from its casual usage. "Entity" can mean a legal entity, a data entity, or a system resource depending on context. Ambiguity in compliance documentation is not a minor quality issue — it is a risk.

The false precision trap

Complex regulatory language can create the illusion of precision while actually obscuring meaning. If a sentence requires re-reading, it needs rewriting — regardless of how technically accurate it is. Accuracy and clarity are not in opposition.

Task orientation over reference orientation

Regulatory and compliance documentation is often structured as reference material: exhaustive lists of rules, conditions, and exceptions. Developer documentation works better when restructured around tasks: "File a SAR," "Screen an entity," "Configure OFAC watchlist integration." The same information is there, but organised around what the reader needs to do, not around what the system can do.

What good documentation looks like

Measurable criteria for developer documentation quality, not aesthetic opinions.

Criterion What to measure Failure signal
Time to first working call How long it takes a developer unfamiliar with the API to make a successful authenticated request Quickstart page requires more than 5 minutes to complete
Error recoverability Whether the error docs tell the developer what to do, not just what went wrong Error table contains only HTTP status codes without actionable guidance
Completeness of failure paths Whether the documentation covers what happens when things go wrong, not just the happy path No documentation for 4xx errors, network failures, or partial-success states
Consistent terminology Whether the same concept is named the same way throughout the documentation set "API key," "access key," "auth token," and "API token" used interchangeably
Scannability Whether a developer can locate the information they need without reading every word Long prose paragraphs with no headings, tables, or code blocks for 300+ words
Example currency Whether code examples work against the current API version Examples that fail because they reference deprecated parameters or endpoints

Self-imposed constraints for this portfolio

Every project in this portfolio was written under the following constraints. These are not aspirational guidelines — they are verifiable by reading the output.

  • No minimizers. "Simply," "just," "easy," "straightforward," "obvious," "clearly" — none appear in any page in this portfolio.
  • Active voice throughout. Every procedural step uses active voice. Passive constructions appear only where the agent is genuinely unknown or irrelevant.
  • Sentence-case headings. No title case except for proper nouns and product names.
  • Second person. "You" is used consistently. "The user," "the developer," and "one" do not appear in procedural sections.
  • Present tense. Documentation describes current behavior. Future tense appears only in migration and changelog content.
  • Every error is actionable. No error page in this portfolio describes an error without also describing what the reader should do about it.
  • No assumption of prior knowledge beyond what is stated. Prerequisites are always listed explicitly at the start of procedural pages.