Information architecture

IA is not a deliverable — it's a series of decisions that happen before you write a single word. This page documents the audience analysis, content model, and structural decisions behind each project in this portfolio.

What information architecture means for documentation

In a software product, IA determines how users navigate and form a mental model of the system. In a documentation set, IA determines three things:

  • What is included — and what is excluded. Every documentation project has a scope decision. Expanding scope without discipline produces sprawl; narrowing it too tightly produces gaps.
  • How content is grouped — whether pages are organised by feature, by task, by user type, or by journey stage. The grouping model should match how readers think about the problem, not how engineers think about the code.
  • How readers navigate — the landmarks, labelling, and progressive disclosure that let a reader locate content without reading everything.

IA principle: structure = audience × task

The right structure for a documentation set is a function of who reads it and what they need to do. The same technical content structured for a developer integrating an API looks completely different from content structured for a compliance officer reviewing an AML system.

Audience analysis methodology

Before structure, before content, before writing: audience definition. Each project in this portfolio started with explicit answers to these questions.

Question What it determines
Who is the primary reader? Vocabulary level, assumed baseline knowledge, tone, and depth of explanation
What are they trying to accomplish? Task orientation, page-level goals, what counts as "done"
What do they already know? What to define and what to assume; where to link instead of explain
What environment are they in? Whether they are coding, debugging, deploying, or auditing — influences format choices
What happens if they get it wrong? Determines the density and prominence of warnings, preconditions, and confirmation steps
Are there secondary audiences? Whether to include audience-specific sections, tabbed content, or separate guides

Per-project IA decisions

The following table documents the primary IA decision for each portfolio project — specifically, the structural choice that was central to making the content usable for its intended audience.

Project Primary audience Central IA decision Rationale
CaseForge API Reference Backend engineers integrating the API Organised by resource type (Cases, Entities, SARs, Webhooks) rather than by journey Developers consulting a reference are looking up a specific endpoint, not reading linearly. Resource-based organization matches lookup behavior.
VaultPay API Docs Engineers building payment integrations, new to the VaultPay API Journey-based structure: Getting Started → Authentication → Payment Flows → Error Handling → Production Onboarding documentation is read linearly the first time. Journey structure matches the developer's actual path through integration.
PayPlus Admin Guide IT admins and system operators deploying and configuring the platform Task-based: each top-level section corresponds to an operator task (Install, Configure, Manage Users, Monitor, Troubleshoot) Operators rarely read documentation front-to-back. They arrive at a specific task. Task-based organization with deep headings supports targeted lookup.
US Payments Hub Payment operations teams, compliance analysts Reference architecture: payment rail as the primary organising principle (ACH, Fedwire, RTP, SWIFT), with cross-rail compliance topics surfaced separately Ops teams specialise by payment rail. Organising by rail first (then by topic within each rail) matches their mental model and prevents cross-rail confusion.
CaseForge Onboarding Kit Customer success teams, enterprise buyers, technical project managers Time-based structure: Phase 1 (Days 1–7) → Phase 2 (Days 8–21) → Phase 3 (Days 22–30) with role assignments per task Onboarding is a linear process with a fixed timeline. Chronological structure gives stakeholders clear milestones and makes blockers visible.
CaseForge SDK Docs Python and Node.js developers using the SDK wrapper Hybrid structure: conceptual landing page + sequential quickstart + reference sections (auth, errors, code samples) + versioning section (changelog, migration) SDK users have two distinct use modes: initial integration (sequential) and ongoing reference (lookup). The hybrid structure serves both without forcing a choice.

Content model

A content model defines the information types used across a documentation set and the rules for each. Consistent content types make documentation more scannable, more maintainable, and easier to localise or reuse.

Information types used in this portfolio

Type Purpose Structure rules
Concept Explains what something is and why it exists What it is → Why it's needed → How it relates to other concepts. No procedural steps. Links to related tasks and references.
Task Guides the reader through completing a specific action Prerequisites → Numbered steps → Expected outcome. One goal per task topic. Steps are imperative ("Click", "Enter", "Run").
Reference Provides complete, lookup-oriented facts (endpoints, parameters, error codes, fields) Tables or definition lists. Consistent structure per entry. No narrative. Links to conceptual and task topics where needed.
Troubleshooting Maps symptoms to causes and resolutions Symptom → Cause → Resolution. Always actionable. Distinguishes developer errors from system errors. Identifies retryable vs. non-retryable conditions.
Release notes Documents changes between versions Version header → Date → Breaking changes first → New features → Bug fixes → Deprecations. Every entry links to affected documentation.

The what/why/how/failure/validate pattern

For complex features and integration patterns, each section follows a five-part structure. This is not a rigid template — it is a completeness check.

  1. What is this?

    A one-sentence definition that orients the reader. Not: "Authentication is a major feature of the API." Yes: "The CaseForge API authenticates requests using API keys or OAuth 2.0 client credentials."

  2. Why does it exist / when do you use it?

    Clarifies the use case and motivates the reader's attention. Without this, readers skip features they need because they don't recognize the relevance.

  3. How do you do it?

    The procedure, with code examples. Specific, testable, complete. Readers should be able to copy-paste the example and have it work.

  4. What can go wrong?

    The failure states, error codes, and edge cases. This is the section most developers read when they get stuck — it carries disproportionate value relative to its length.

  5. How do you verify it worked?

    The expected output, confirmation signal, or test command. Removes ambiguity about whether the procedure succeeded.

Progressive disclosure

Progressive disclosure is the practice of presenting information in layers: the most common case first, edge cases on demand. In documentation, this means structuring content so that readers see what they need for the most common scenario without being buried in configuration options, edge cases, and footnotes.

How this portfolio implements progressive disclosure

Landing pages

Every project's index.html shows the three most important things: what the product is, what the documentation covers, and how to start. Advanced configuration, edge cases, and exhaustive references are one click away — not on the first page.

Quickstart vs. full reference

Quickstart pages use the minimal happy-path configuration. They do not cover every authentication method, every parameter, or every edge case. Full reference documentation covers exhaustively. These are linked but distinct — a reader should not have to read the full reference to complete a quickstart.

Code samples: minimal to complete

Code samples follow a progression within each topic: minimum working example first, then progressively more complete versions showing additional parameters, error handling, pagination, and production-ready patterns.

Admonitions for optional depth

Callout boxes (note, tip, warning) surface secondary information that some readers need without interrupting the main flow for readers who don't. A warning about OFAC obligations matters for compliance engineers — it should not be buried in the main text where it adds noise for developers who have already handled it.

Navigation is the physical embodiment of information architecture. Poor navigation makes strong content invisible. The decisions in this portfolio:

  • Fixed left sidebar. Developer documentation is consulted while working, often across multiple browser windows. A fixed sidebar keeps context always visible without requiring scroll-to-top to navigate.
  • Section labels above link groups. Section labels (GETTING STARTED, REFERENCE, VERSIONING) help readers locate the category of information they need before reading individual link names.
  • Active state highlighting. The current page is visually highlighted in the sidebar on every load, using a small JS utility that matches window.location.pathname against nav link href attributes. This grounds the reader's position in the documentation.
  • Breadcrumbs on inner pages. Breadcrumbs on non-top-level pages reassure readers that they can navigate back without losing their place. They also communicate the documentation's hierarchy at a glance.
  • No deep nesting in sidebar. Navigation links are two levels maximum: section label + item. Deeper nesting adds visual complexity without proportional value. If a topic genuinely requires sub-navigation, in-page jump links (anchors) serve the purpose.