Structure and Information Architecture
Structure and Information Architecture
Organize technical documentation so readers find what they need, when they need it, with the right level of detail for their current task
Table of Contents
- 🎯 Introduction
- 📊 Progressive disclosure: layering complexity
- 🏗️ The LATCH framework
- 📋 Table of contents strategies
- 🧭 Navigation hierarchies
- 📄 Page structure patterns
- 🎨 Content design principles
- 🔗 Cross-referencing strategies
- Series architecture and planning
- 📌 Applying architecture to this repository
- ✅ Conclusion
- 📚 References
🎯 Introduction
Information architecture determines whether users find and understand your documentation. Even perfectly written content fails if users can’t locate it or can’t determine which sections apply to their needs.
This article explores:
- Progressive disclosure - Revealing complexity in layers appropriate to user needs
- LATCH framework - Five universal organizing principles (Location, Alphabet, Time, Category, Hierarchy)
- TOC strategies - Designing tables of contents that serve navigation and comprehension
- Navigation hierarchies - Creating pathways for different user journeys
- Page structure - Patterns for organizing individual documents
- Content design principles - Content-first design, structured content models, and topic-based authoring
Prerequisites: Understanding of documentation foundations and the Diátaxis framework is helpful.
📊 Progressive disclosure: layering complexity
Progressive disclosure presents information in layers, revealing complexity gradually based on user needs. This principle, borrowed from interface design, reduces cognitive load while ensuring advanced users can access complete information.
The principle
Core idea: Show users the minimum information needed for their current task; provide pathways to more detail when needed.
Applied to documentation:
- Surface level: What most users need, immediately visible
- Detail level: Supporting information, available on demand
- Expert level: Edge cases, advanced configuration, behind-the-scenes
Implementation patterns
Pattern 1: Lead with essentials, depth below
## Authentication
Authenticate requests using Bearer tokens in the Authorization header.
### Quick Start (Surface)
```bash
curl -H "Authorization: Bearer YOUR_TOKEN" https://api.example.com/usersToken Management (Detail)
Tokens expire after 24 hours. Refresh tokens using the /auth/refresh endpoint…
Advanced: Custom Token Lifetimes (Expert)
For enterprise deployments, configure token lifetime in auth.config.json…
**Pattern 2: Summary boxes with expansion**
```markdown
> **TL;DR:** Use `npm install package-name` to install packages.
> For advanced options, see [Installation Options](#installation-options).
## Installation
The npm package manager handles dependencies automatically...
[detailed explanation follows]Pattern 3: Audience-specific pathways
## Getting Started
Choose your path:
- **[Quick Start](#quick-start)** - Get running in 5 minutes
- **[Standard Setup](#standard-setup)** - Full installation with configuration
- **[Enterprise Deployment](#enterprise-deployment)** - High-availability cluster setupProgressive disclosure by Diátaxis type
| Content Type | Surface Level | Detail Level | Expert Level |
|---|---|---|---|
| Tutorial | “Do this, see that” | “Here’s why this works” | Links to explanation |
| How-to | Steps to accomplish goal | Variations and options | Edge cases, troubleshooting |
| Reference | Signature, brief description | Parameters, return values | Implementation notes |
| Explanation | Core concept | Supporting details, context | Academic depth, research |
Anti-patterns to avoid
❌ Information dumping: All details on first exposure > “The authentication system supports OAuth 2.0, SAML 2.0, OpenID Connect, LDAP, Active Directory, custom JWT, API keys with scopes, mTLS, and webhook-based verification. OAuth 2.0 supports authorization code flow, implicit flow, client credentials, and device code flow…”
✅ Progressive alternative: > “Authentication supports multiple methods. Most integrations use OAuth 2.0 (Quick Start). For enterprise SSO, see SAML Configuration.”
❌ Hiding essential information: Critical details buried too deep > Links labeled “Learn more” with no indication of content importance
✅ Progressive alternative: > Explicit labels: “Required for production: Configure rate limiting before deployment”
🏗️ The LATCH framework
Richard Saul Wurman’s LATCH framework identifies five fundamental ways to organize information. Every organizational scheme is a variation of these five approaches.
L - Location
Organize by physical or logical position
Best for:
- Geographic information
- Spatial relationships
- Physical system components
- Directory structures
Documentation examples:
## Azure Regions
- East US
- West Europe
- Southeast Asia
## File System Structure
/src
/components
/utils
/docs
/testsWhen to use: When physical or logical position is the primary concern; when users think “where is this?”
A - Alphabet
Organize in alphabetical order
Best for:
- Reference lookups
- Glossaries
- API endpoints (by name)
- Configuration options
Documentation examples:
## API Methods
- `authenticate()`
- `createUser()`
- `deleteRecord()`
- `getStatus()`
## Configuration Options
| Option | Description |
|--------|-------------|
| `apiKey` | Your API key |
| `baseUrl` | Base URL for requests |
| `timeout` | Request timeout in ms |When to use: When users know what they’re looking for by name; for exhaustive reference lists.
Limitation: Alphabetical order assumes users know the exact term. Provide search or index for discovery.
T - Time
Organize chronologically or by sequence
Best for:
- Procedures (step 1, step 2…)
- Changelogs and release notes
- Historical documentation
- Workflows and processes
Documentation examples:
## Release History
- **v2.0.0** (2026-01-14) - Major authentication overhaul
- **v1.5.2** (2025-12-01) - Security patches
- **v1.5.1** (2025-11-15) - Bug fixes
## Deployment Steps
1. Build the application
2. Run tests
3. Deploy to staging
4. Verify staging
5. Deploy to productionWhen to use: When sequence matters; when users need to understand “what comes next” or “what happened when.”
C - Category
Organize by type, theme, or topic
Best for:
- Conceptual groupings
- Feature documentation
- Topic-based organization
- Product areas
Documentation examples:
## Documentation by Topic
- **Authentication** - OAuth, API keys, SSO
- **Data Storage** - Databases, file storage, caching
- **Messaging** - Queues, pub/sub, webhooks
## Components by Type
- **UI Components** - Buttons, forms, modals
- **Data Components** - Tables, charts, grids
- **Layout Components** - Headers, sidebars, footersWhen to use: When users think in terms of concepts or features; when content naturally groups by topic.
H - Hierarchy
Organize by importance, magnitude, or rank
Best for:
- Priority ordering
- Severity levels
- Organizational structures
- Skill-level content
Documentation examples:
## Error Severity
- **Critical** - System down, data loss risk
- **High** - Major functionality impaired
- **Medium** - Feature degraded
- **Low** - Cosmetic issues
## Learning Path
- **Beginner** - Fundamentals
- **Intermediate** - Advanced features
- **Expert** - Architecture and optimizationWhen to use: When relative importance guides user decisions; when some information is more critical than others.
Combining LATCH principles
Real documentation combines multiple LATCH approaches:
Example: API Reference
- Category: Endpoints grouped by resource (users, orders, products)
- Alphabet: Methods listed A-Z within each category
- Time: Changelog organized chronologically
- Hierarchy: Deprecated methods marked as lower priority
Example: This Repository
- Category: Content by topic (tech, howto, issues, events)
- Time: Date-prefixed folders (20250814 topic/)
- Hierarchy: Numbered folders (01.00-news, 02.00-events…)
- Alphabet: Within categories, often alphabetical
📋 Table of contents strategies
Tables of contents serve two functions: navigation (getting to content) and orientation (understanding structure).
TOC design principles
1. Reflect actual structure
- TOC entries should match heading text exactly
- Hierarchy should match document hierarchy
- No phantom entries (TOC items without corresponding sections)
2. Balance depth and scannability
- 5-9 items ideal for scannability (Miller’s Law)
- 3 levels maximum for most documents
- Flatten if structure is too deep
3. Use parallel construction
- Consistent grammatical structure
- All nouns, all verbs, or all phrases
✅ Parallel:
- Installing the CLI
- Configuring Authentication
- Deploying Applications
- Troubleshooting Errors❌ Not parallel:
- Installing the CLI
- How to Configure Authentication
- Application Deployment
- When You Have ErrorsTOC patterns
Pattern 1: Flat TOC (5-7 sections)
Best for focused articles with linear flow.
## Table of Contents
- [Introduction](#introduction)
- [Prerequisites](#prerequisites)
- [Installation](#installation)
- [Configuration](#configuration)
- [Usage](#usage)
- [Troubleshooting](#troubleshooting)Pattern 2: Nested TOC (grouped sections)
Best for comprehensive guides with distinct parts.
## Table of Contents
- [Part 1: Setup](#part-1-setup)
- [Installation](#installation)
- [Configuration](#configuration)
- [Part 2: Usage](#part-2-usage)
- [Basic Operations](#basic-operations)
- [Advanced Features](#advanced-features)
- [Part 3: Reference](#part-3-reference)
- [API Documentation](#api-documentation)
- [Configuration Options](#configuration-options)Pattern 3: Topic-based TOC (conceptual groups)
Best for explanation articles or conceptual documentation.
## Table of Contents
- [Core Concepts](#core-concepts)
- [Authentication](#authentication)
- [Data Management](#data-management)
- [Performance Optimization](#performance-optimization)
- [Security Considerations](#security-considerations)Auto-generated vs. manual TOCs
Auto-generated TOCs (Quarto, MkDocs, etc.):
- ✅ Always synchronized with content
- ✅ Less maintenance
- ❌ May include too many levels
- ❌ Less control over presentation
Manual TOCs:
- ✅ Curated, intentional structure
- ✅ Can include descriptions
- ❌ Can become out of sync
- ❌ Maintenance burden
This repository’s approach: Manual TOCs for key articles (control over presentation), with Quarto’s automatic navigation sidebar for site-wide navigation.
📄 Page structure patterns
Individual pages follow structural patterns that support comprehension and navigation.
The standard article pattern
# Title
> Subtitle or description
## Table of Contents
[Navigation links]
## Introduction
- What this covers
- Why it matters
- Prerequisites
## Main Content Sections
[Organized by topic/sequence]
### Subsections as needed
## Conclusion
- Key takeaways
- Next steps
## References
[Cited sources]
<!-- Validation Metadata -->
[Tracking YAML]The reference pattern
# API Reference: [Resource Name]
## Overview
Brief description and purpose
## Endpoints
### GET /resource
[Description, parameters, response, examples]
### POST /resource
[Description, parameters, response, examples]
## Objects
### ResourceObject
[Properties, types, descriptions]
## Errors
[Error codes, meanings, resolution]The how-to pattern
# How to [Accomplish Task]
## Overview
What you'll accomplish
## Prerequisites
- Required tools
- Required access
- Required knowledge
## Steps
### Step 1: [Action]
[Instructions]
### Step 2: [Action]
[Instructions]
## Verification
How to confirm success
## Next Steps
Related tasks
## Troubleshooting
Common issues and solutionsThe tutorial pattern
Note: The code block below is a template example showing the recommended structure for tutorial-type content. The
What You'll LearnandWhat You've Learnedsections are part of the tutorial pattern, not standard article structure used in this series. For the article structure this series follows, see The Standard Article Pattern above.
# Tutorial: [Learning Goal]
## What You'll Learn
- Skill 1
- Skill 2
## Prerequisites
- Required knowledge level
- Setup requirements
## Part 1: [Foundation]
### [Guided activity]
[Step-by-step with explanations]
### [Practice checkpoint]
[Verify understanding]
## Part 2: [Building]
[Progressive complexity]
## Part 3: [Completing]
[Final product]
## What You've Learned
Summary of skills acquired
## Next Steps
Further learning pathsWikipedia’s article structure
Wikipedia provides a well-tested pattern for encyclopedic content:
# Article Title
[Lead section - standalone summary]
## Contents
[Auto-generated TOC]
## History / Background
[Context and origins]
## [Main topic sections]
[Body content]
## See Also
[Related articles]
## Notes
[Explanatory footnotes]
## References
[Citation list]
## External Links
[Curated outside resources]Key Wikipedia innovations:
- Lead section stands alone: First paragraph summarizes entire article
- “See also” for discovery: Related topics for exploration
- Notes vs. References: Explanatory notes separated from source citations
🎨 Content design principles
Page structure patterns describe how to arrange individual documents. Content design principles address the higher-level question: how do you decide what content to create and how to break it apart? These principles guide decisions before you start writing a single page.
Content-first design
Content-first design means defining the content model—what information exists, who needs it, and in what context—before choosing layout, navigation, or tooling.
The principle:
- Identify the information — List every concept, procedure, and reference the audience needs
- Prioritize by user task — Rank information by frequency of need and criticality
- Define relationships — Map which content pieces depend on, extend, or duplicate each other
- Choose structure last — Select page types, navigation, and templates only after the content model is clear
Why this matters for technical documentation:
| Design approach | Risk | Symptom |
|---|---|---|
| Template-first | Content forced into ill-fitting containers | Sections with one sentence or “N/A” filler |
| Tool-first | Content constrained by tooling limits | Docs restructured whenever tooling changes |
| Content-first | None (desired approach) | Structure emerges naturally from content needs |
Practical example: Before creating a new article in this series, the gap analysis document (gap-analysis-context-vs-articles.md) identifies what content is missing and where it belongs. Only after confirming the gap do we choose whether it becomes a new article, a section in an existing article, or a cross-reference.
Structured content models
Structured content separates content from presentation by defining reusable, typed content components with explicit relationships.
Key concepts:
- Content types — Named categories of content with defined fields (e.g., “Tutorial” has prerequisites, steps, verification; “Reference” has syntax, parameters, return values)
- Metadata schemas — Structured attributes attached to each content unit (this repository uses Quarto YAML front matter and bottom-block validation metadata)
- Content reuse — Write once, reference many times; avoid duplicating explanations across articles
- Separation of concerns — Content (Markdown), presentation (Quarto/SCSS), and structure (_quarto.yml) live in separate layers
How this repository applies structured content:
| Layer | Implementation | Example |
|---|---|---|
| Content types | Article template with required sections | article-template.md |
| Metadata schema | Dual YAML blocks (Quarto + validation) | Top YAML for rendering, bottom HTML comment for tracking |
| Reuse via reference | Cross-references instead of duplication | “See Art. 01 for voice principles” |
| Presentation layer | Quarto + cerulean.scss | Consistent rendering independent of content changes |
Anti-pattern: unstructured content
- Copy-pasting the same explanation into multiple articles (creates maintenance debt)
- Mixing rendering instructions into prose (breaks when tooling changes)
- Omitting metadata (makes validation, search, and lifecycle management impossible)
For the lifecycle implications of structured vs. unstructured content, see Article 10: Documentation Lifecycle and Maintenance.
Content density and depth by article type
Not every article needs the same level of detail. A tutorial that explains the mathematical derivation behind readability formulas is misplacing depth; a reference that skips parameter descriptions is withholding it. Content density is the ratio of essential information to supporting material within a section.
The appropriate depth depends on the article’s Diátaxis type and its role in the series:
| Article type | Appropriate depth | Density target | Example from this series |
|---|---|---|---|
| Explanation (concepts) | Deep — teach the “why” with models, frameworks, and theory | High density; every paragraph advances understanding | Art. 09’s LaTeX formula breakdowns for readability metrics |
| How-to (task guidance) | Moderate — enough context to execute, not to theorize | Medium density; context supports action | Art. 07’s AI prompting patterns with step-by-step workflows |
| Reference (lookup) | Shallow but exhaustive — cover every option without editorializing | High density; minimal prose, maximum data | Art. 04’s code documentation patterns (tables, templates) |
| Tutorial (learning) | Progressive — start shallow, deepen as learner gains confidence | Low-to-medium; scaffolded with checkpoints | Art. 00’s foundations article building from principles to frameworks |
Signals that depth is wrong:
| Signal | Problem | Fix |
|---|---|---|
| Readers skip long sections | Too deep for the article type | Extract deep content into a companion explanation article; link to it |
| Readers ask follow-up questions the article should answer | Too shallow | Add the missing analytical layer; ensure the density matches the Diátaxis type |
| Code examples lack context | Depth mismatch — reference-level content in a tutorial-type article | Add scaffolding prose around the code explaining what it demonstrates |
| Lengthy theoretical preambles before practical guidance | Deep explanation in a how-to article | Move theory to a blockquote or “Background” subsection; lead with the task |
The depth-consistency rule: Within a single article, maintain consistent depth. If one subsection goes three levels deep (concept → framework → worked example), all major subsections should reach similar depth. An article that alternates between surface treatment and deep analysis feels uneven and erodes reader trust.
See also: Article 11 for guidance on which visual types are appropriate at each depth level.
🔗 Cross-referencing strategies
Cross-references connect related content, supporting both navigation and comprehension.
Types of cross-references
Inline references: Context-specific links within prose > “For authentication options, see the Security Guide.”
See also sections: Related content collections
## See Also
- [OAuth 2.0 Deep Dive](./oauth-deep-dive.md)
- [API Security Best Practices](../security/api-security.md)
- [Token Management](./token-management.md)Prerequisites: Required prior knowledge
## Prerequisites
Before starting this tutorial, complete:
- [Getting Started Guide](../getting-started.md)
- [Authentication Setup](./auth-setup.md)Next steps: Forward navigation
## Next Steps
- [Configure advanced options](./advanced-config.md)
- [Deploy to production](../deployment/production.md)Cross-reference best practices
1. Make links meaningful
❌ Vague: > “For more information, click here.”
✅ Descriptive: > “For detailed authentication options, see Configuring OAuth 2.0.”
2. Indicate link purpose
- For background, see [History of REST](./rest-history.md) (explanation)
- To implement this, follow [Setting up REST API](./rest-setup.md) (how-to)
- For endpoint details, see [REST API Reference](./rest-reference.md) (reference)3. Use consistent patterns
This repository’s pattern from documentation.instructions.md:
See [Article Title](relative/path/to/article.md) for [brief description of what reader will find].4. Avoid circular references
Map cross-references to ensure they form useful pathways, not loops.
5. Validate links regularly
Broken cross-references undermine trust. See scripts/check-links.ps1 for link validation.
Series architecture and planning
Individual articles need structure. So do article series. This section covers how to plan a documentation series from scratch—scoping the series, determining article count, designing the learning progression, defining article boundaries, and managing length.
Scoping a documentation series
Before writing the first article, answer these four questions:
| Question | What it determines | Example answer (this series) |
|---|---|---|
| What’s the domain boundary? | Which topics are in-scope and which belong elsewhere | Technical writing for documentation sites—not creative writing, journalism, or marketing copy |
| Who’s the audience? | Knowledge level, goals, constraints | Technical professionals who write documentation as part of their role, not full-time technical writers |
| What’s the learning progression? | Prerequisite chain from foundations to advanced | Foundations → style → structure → accessibility → code docs → validation → citations → AI → consistency → readability → lifecycle → visuals → globalization |
| What’s the scope ceiling? | When is the series “complete enough”? | When a reader can produce, validate, and maintain a quality documentation site using the principles taught |
The scope test: If a proposed article doesn’t serve the audience’s learning progression or falls outside the domain boundary, it belongs in a different series or as a standalone piece.
Designing the learning progression
A series isn’t just a collection of articles on related topics—it’s a prerequisite chain where each article builds on concepts from earlier ones.
Mapping technique:
- List all core concepts the series must cover
- Identify dependencies — Which concepts require understanding of prior concepts?
- Group into articles — Cluster related concepts that share a natural narrative arc
- Order by dependency — Ensure no article assumes knowledge from a later article
- Verify with a “cold reader” test — Could someone read article N without having read article N+1?
Prerequisite chain example (this series):
Art. 00 Foundations ──→ Art. 01 Style ──→ Art. 02 Structure
│ │ │
│ ▼ ▼
│ Art. 03 Accessibility Art. 04 Code docs
│ │
▼ ▼
Art. 05 Validation ──→ Art. 06 Citations ──→ Art. 07 AI-enhanced
│
▼
Art. 08 Consistency ──→ Art. 09 Readability ──→ Art. 10 Lifecycle
│
▼
Art. 11 Visuals ──→ Art. 12 GlobalKey principle: Later articles may reference earlier ones, but readers shouldn’t need to re-read earlier articles to understand the current one. Brief recaps (under 100 words) are acceptable per the series redundancy policy.
Determining article count and boundaries
There’s no magic number. Article count emerges from the intersection of concept clusters and reader endurance.
Splitting criteria — when one article should become two:
| Signal | Example | Action |
|---|---|---|
| Two distinct audiences | Developers AND managers both need the content | Split into audience-specific articles |
| Two distinct purposes | Explaining a concept AND providing a step-by-step procedure | Split into explanation + how-to |
| Length exceeds reader endurance | Over 1,000 lines or 25+ minutes reading time | Look for a natural split point |
| Subsection has independent value | A subsection is frequently cross-referenced from other articles | Extract to its own article |
| Different update cadences | One section changes monthly, another is permanent | Split to enable independent maintenance |
Merging criteria — when two articles should become one:
| Signal | Example | Action |
|---|---|---|
| Combined length under 500 lines | Two thin articles that always link to each other | Merge and redirect |
| Identical audience and purpose | Two how-to guides that readers always use together | Merge into a single guide |
| One article is purely setup for the other | “Prerequisites” article + “Main content” article | Merge with prerequisites as a section |
Article scope and length guidelines
Articles in a series should be comparable in depth and reading time. Extreme variance signals scope problems.
Length benchmarks:
| Article length | Assessment | Action |
|---|---|---|
| Under 400 lines | Likely too thin—may lack sufficient depth or examples | Consider expanding, or merging with a related article |
| 400–800 lines | Sweet spot for most articles | Normal range; no action needed |
| 800–1,000 lines | Acceptable for complex topics with many code examples | Review for sections that could be extracted |
| Over 1,000 lines | Likely too long—reader fatigue and maintenance burden | Identify splitting opportunities using the criteria above |
This series’ length distribution:
| Range | Articles | Assessment |
|---|---|---|
| 550–700 lines | Art. 03, 06, 08, 10 | Concise and focused |
| 700–850 lines | Art. 00, 01, 02, 04, 09, 11, 12 | Standard depth |
| 850–1,000 lines | Art. 05, 07 | Complex topics justified by scope (validation has seven dimensions; AI has rapidly evolving tooling) |
Scope check: If an article keeps growing during writing, it probably needs splitting. If you can’t write more than 400 lines, the topic may be too narrow for a standalone article.
Audience-segmented reading paths
Different readers need different paths through a series. The four user journeys from navigation by user journey map to distinct reading paths:
The Explorer (browsing to learn): > Start with Art. 00 (Foundations) → skim TOCs of Art. 01–12 → read articles that match your interests
The Beginner (building skills): > Art. 00 → Art. 01 → Art. 02 → Art. 03 → Art. 04 → Art. 05 (sequential, foundations first)
The Practitioner (solving problems): > Jump directly to the relevant article via TOC or search → follow cross-references for prerequisites as needed
The Reviewer (validating quality): > Art. 05 (Validation) → Art. 08 (Consistency) → Art. 01 (Style) → Art. 09 (Readability)
Implementing reading paths:
- Article introductions should include a prerequisites list so practitioners can self-assess: “This article assumes familiarity with [X].”
- Next Steps sections should suggest both the sequential next article AND topically related articles for non-sequential readers.
- Cross-references should indicate the Diátaxis type of the target, so readers know whether they’re navigating to an explanation, how-to, or reference: “See Article 05 for validation frameworks (explanation)” vs. “Follow the validation workflow (how-to).”
Why this matters: Without reading paths, every reader enters the series the same way—by starting at Art. 00 and reading sequentially. This works for beginners but frustrates experienced practitioners who only need specific articles. Explicit paths respect different readers’ time and expertise levels.
Series evolution strategies
A documentation series isn’t frozen at launch. Articles get added, removed, merged, split, and reordered as the domain evolves. Without explicit evolution strategies, organic growth introduces the same problems you planned away—inconsistent depth, broken cross-references, and orphaned prerequisites.
Adding an article:
- Validate the gap — Check the concept coverage matrix to confirm the topic isn’t already covered
- Assign a position — Place the new article where it fits in the prerequisite chain; update
series_positionmetadata in downstream articles if numbering shifts - Wire cross-references — Add forward links from prerequisite articles and back-links from the new article to its foundations
- Update reading paths — Revise the audience-segmented paths above to include the new article where appropriate
- Update totals — Increment
total_articlesmetadata across all articles in the series
Removing or deprecating an article:
| Step | Action | Why |
|---|---|---|
| 1 | Identify all inbound cross-references | Removing an article breaks every link pointing to it |
| 2 | Redirect or replace references | Point existing links to the closest surviving content |
| 3 | Absorb unique content | If the removed article contains concepts found nowhere else, migrate those sections into a surviving article |
| 4 | Follow the deprecation lifecycle | Use the deprecation process from Article 10: mark deprecated → remove from navigation → maintain access → redirect → archive |
| 5 | Update metadata | Decrement total_articles; adjust series_position values |
Splitting an article:
Use the splitting criteria from earlier in this section. When you split:
- Preserve the original URL — Redirect it to the first of the two new articles, or to a disambiguation page if both halves are equally important
- Distribute cross-references — Each inbound link should point to whichever new article contains the referenced content
- Add mutual cross-references — The two new articles should link to each other: “This article was split from [original]. For [other half’s topic], see [sibling article].”
Merging articles:
When two articles are thin (under 400 lines each) and share the same audience and purpose:
- Choose the more intuitive article title as the survivor
- Redirect the absorbed article’s URL to the survivor
- Combine content, eliminating pure duplication and converting near-duplicates into a single authoritative treatment
- Update all cross-references that pointed to the absorbed article
Reordering articles:
Reordering changes the prerequisite chain and reading paths. Minimize disruption by:
- Renumbering files — Keep filenames sequential (
00-,01-, etc.) so the file system reflects the intended learning order - Batch-updating metadata — Change
series_positionin all affected articles in a single pass, not incrementally - Reviewing cross-references — “See the next article” or “the previous article” language must match the new order
- Announcing the change — If readers have bookmarked specific positions, a brief note in the series introduction explaining the reorder helps orient returning readers
See also: Article 08 for consistency maintenance strategies during series changes. Article 10 for the full deprecation and archival lifecycle.
📌 Applying architecture to this repository
Current architecture
LATCH application:
- Hierarchy: Numbered top-level folders (01.00, 02.00, 03.00…)
- Category: Topic-based organization within tech/ folder
- Time: Date prefixes on event and news folders
- Alphabet: Often within categories (Azure, Data, GitHub…)
Diátaxis mapping:
- Tutorials: GETTING-STARTED.md, introduction articles
- How-to: 04.00-howto/ folder
- Reference: .copilot/context/, validation-criteria.md
- Explanation: 03.00-tech/ conceptual articles
Progressive disclosure implementation
Surface level: README.md, GETTING-STARTED.md Detail level: Topic articles in 03.00-tech/ Expert level: Context files in .copilot/context/, source code
Structural standards
From documentation.instructions.md:
Required article elements:
- YAML front matter (Quarto metadata)
- Title matching filename
- Table of Contents (for articles > 500 words)
- Introduction stating scope
- Conclusion with key takeaways
- References section (for articles with citations)
- Validation metadata (bottom YAML)
✅ Conclusion
Information architecture determines documentation usability. The right structure helps readers find, understand, and act on information efficiently.
Key takeaways
- Progressive disclosure matters — Layer complexity so users see what they need without being overwhelmed by what they don’t
- LATCH provides organizing options — Location, Alphabet, Time, Category, Hierarchy cover all information organization needs
- TOCs serve dual purposes — Navigation and orientation; design for both through careful structure
- Navigation supports multiple journeys — Explorers, searchers, followers, and returners need different pathways
- Page structure follows patterns — Articles, references, how-tos, and tutorials each have proven structural templates
- Content design precedes page design — Define what information exists and who needs it before choosing structure; use structured content models and topic-based authoring for maintainability and reuse
- Cross-references connect content — Meaningful links with clear purposes support discovery and comprehension
Next steps
- Next article: 03-accessibility-in-technical-writing.md — Ensuring documentation works for all users
- Related: 00-foundations-of-technical-documentation.md — Diátaxis framework context
- Related: 01-writing-style-and-voice-principles.md — Voice principles that complement structure
📚 References
Information architecture foundations
Information Architecture: For the Web and Beyond (4th Edition) 📗 [Verified Community]
Rosenfeld, Morville, and Arango’s foundational text on information architecture principles.
LATCH: The Five Hat Racks - Richard Saul Wurman 📗 [Verified Community]
Original source for the five universal ways to organize information.
Don’t Make Me Think - Steve Krug 📗 [Verified Community]
Usability principles applicable to documentation navigation and structure.
Progressive disclosure
Progressive Disclosure - Nielsen Norman Group 📗 [Verified Community]
Foundational article on progressive disclosure in interface design, applicable to documentation.
The Principle of Least Astonishment 📘 [Official]
Wikipedia’s explanation of designing systems (including documentation) to match user expectations.
Documentation structure standards
Diátaxis - Tutorials 📗 [Verified Community]
Structural guidance for tutorial-type documentation.
Google Developer Documentation - Document Structure 📘 [Official]
Google’s guidance on structuring technical documents.
Microsoft Writing Style Guide - Content Planning 📘 [Official]
Microsoft’s approach to content structure and organization.
Wikipedia Manual of Style - Layout 📘 [Official]
Wikipedia’s article structure standards and section ordering.
Repository-specific documentation
_quarto.yml [Internal Reference]
This repository’s navigation configuration and site structure.
Documentation Instructions - Structure [Internal Reference]
Required article elements and structural standards for this repository.
generate-navigation.ps1 [Internal Reference]
Script for generating navigation structure from folder hierarchy.