Skip to content

Clarify distinction between errors and exceptions in documentation#34

Merged
Reefact merged 3 commits into
mainfrom
claude/faq-exception-handling-g4i791
Jul 6, 2026
Merged

Clarify distinction between errors and exceptions in documentation#34
Reefact merged 3 commits into
mainfrom
claude/faq-exception-handling-g4i791

Conversation

@Reefact

@Reefact Reefact commented Jul 6, 2026

Copy link
Copy Markdown
Owner

Summary

This PR refines the documentation to establish a clearer conceptual distinction between errors (as structured knowledge artifacts) and exceptions (as runtime mechanisms). The changes emphasize that FirstClassErrors transforms how errors are understood and documented, not the exception mechanism itself.

Key Changes

  • Terminology refinement: Changed "exceptions" to "errors" in key taglines and descriptions across README files (English and French) to better reflect the library's focus on error semantics rather than exception mechanics
  • Conceptual clarity: Updated core concept documentation to explicitly state that exceptions remain the signaling mechanism, while the library elevates the error data they carry into structured knowledge
  • Design principle updates: Refined language in design principles to clarify that Outcome<T> allows errors to be "carried as structured data" rather than "used as structured error information," better distinguishing between the error itself and how it's transported
  • FAQ improvements: Enhanced FAQ responses to clarify that the library doesn't replace exceptions but transforms the error knowledge they convey—from mere technical signals into documented knowledge units

Notable Details

All changes are documentation-only and maintain consistency across both English and French versions. The updates reinforce the library's core philosophy: treating errors as first-class knowledge artifacts while preserving exceptions as the underlying mechanism for signaling and propagating failures.

claude added 3 commits July 6, 2026 09:42
The 'Why not just use normal exceptions?' answer said the library
'turns exceptions from technical signals into documented knowledge
units', which conflates the exception (the mechanism that signals and
propagates a failure) with the error it carries. Reword so the exception
stays the signaling/handling mechanism and the *error* is what becomes a
documented knowledge unit, matching the rest of the model (Error as a
first-class concept, exceptions obtained via error.ToException()).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vd5W4xp6DiJdNUsRTmKXpu
The opening sentence said the library 'treats exceptions as structured
knowledge', reusing the same conflation just fixed in the FAQ. Reword so
the exception stays the mechanism that signals and propagates a failure,
and the *error* it carries is what becomes structured knowledge.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vd5W4xp6DiJdNUsRTmKXpu
Corpus-wide pass following the FAQ/CoreConcepts fixes. Same conflation
appeared in three more spots, where the *exception* (the throwing/
transport mechanism) was made the subject of a semantic claim that
belongs to the *error*:

- README (fr/en) tagline: 'Turn your exceptions into ... knowledge' ->
  'Turn your errors into ...'. The error is the knowledge unit.
- README (fr/en) 'Exception or not?' callout: reworded so the same
  *error* is what you either throw as a runtime signal or transport as
  structured data via Outcome (the Outcome path throws no exception).
- DesignPrinciples (fr/en): 'allowing exceptions to be used as
  structured error information through Outcome<T>' -> 'allowing errors
  to be carried as structured data through Outcome<T> instead of
  thrown'. This also removes a contradiction with the preceding
  paragraph, which states the library separates semantics from mechanics.

Reviewed the rest of doc/ (UsagePatterns, BestPractices, Comparison,
OperationalIntegration, pipeline, renderers, i18n, analyzers): the
error/exception distinction already holds there.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Vd5W4xp6DiJdNUsRTmKXpu
@Reefact Reefact merged commit ddfa34c into main Jul 6, 2026
2 checks passed
@Reefact Reefact deleted the claude/faq-exception-handling-g4i791 branch July 6, 2026 20:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants