liveBook · Manning

Executable documentation

As explained in Build High Value Software Systems

Documentation expressed in executable or automatically checked artifacts so it can be verified against the system.

Executable documentation encodes system knowledge in artifacts that can be run or checked, so incorrect or outdated guidance is more likely to be caught. Unlike a wiki page that can quietly go stale, a test or setup script can fail when it no longer matches the system. section 13.5

Use it to make important knowledge easier to find and verify:

  • Name tests for business rules and assert the permitted and rejected outcomes. section 13.4.2
  • Make setup scripts, test suites, and deployment pipelines part of onboarding guidance; use architectural decision records to explain why the system is designed as it is. section 13.5
Listing 13.2 Tests as executable documentation of business rules
def test_refund_exceeding_original_amount_is_rejected():
    order = create_order(amount_cents=5000)
    result = process_refund(order, refund_cents=5001)
    assert result.status == "REJECTED"
    assert result.reason == "Refund exceeds original transaction amount"
 
def test_partial_refund_reduces_remaining_refundable_amount():
    order = create_order(amount_cents=5000)
    process_refund(order, refund_cents=2000)
    result = process_refund(order, refund_cents=3001)
    assert result.status == "REJECTED"
    assert result.reason == "Refund exceeds remaining refundable amount"

The refund tests state two business rules through descriptive names and assertions: refunds cannot exceed the original or remaining refundable amount. section 13.4.2

How Build High Value Software Systems covers it

How deep it goes
Demonstrates business-rule tests with named cases and assertions, then recommends setup scripts, test suites, and deployment pipelines.
Examples
Uses refund tests that reject amounts exceeding the original transaction or remaining refundable balance.
What you can do after
Apply it by documenting business rules in tests and replacing stale onboarding instructions with runnable setup and deployment artifacts.
How it connects
Connects tests and business rules with onboarding, setup scripts, deployment pipelines, and architectural decision records.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Build High Value Software Systems. The section links point to the parts of the book it draws on.