Clarify distinction between errors and exceptions in documentation#34
Merged
Conversation
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
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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
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 transportedNotable 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.