Finalize documentation comparison and navigation#124
Merged
Conversation
The comparison page and the documentation map are entry points read by people who do not know FirstClassErrors yet. Gloss the library-specific vocabulary they lean on, in both languages: - introduce Outcome as the success-or-failure result type in the comparison's topic sentence; - gloss transience, interaction direction, and port in the comparison table rows so they can be evaluated without the taxonomy page; - mark Code.PaymentDeclined and ContextKey.PaymentId as application-defined constants and show the literal stable code, matching what the ErrorOr sample exposes; - say what the generated catalog is at its mention; - clarify transport and catalog in the map's discovery entries, and drop the hedge sentence about focused reference pages in newer documentation versions. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUaMS5EHzAdQHBJzrYvKTj
…ntation-navigation
Address review feedback on the neutrality of the comparison page: - State up front that the scenario emphasizes error stability, diagnosis, and documentation (FirstClassErrors' core), and that other scenarios — heavy multi-error validation or intensive functional composition — can favor ErrorOr or FluentResults. - Give FirstClassErrors a minimal Outcome example of comparable length to the ErrorOr and FluentResults ones, then move the factory, exception, and catalog/versioning material into a dedicated "What FirstClassErrors adds to the result model" section, so the first read is symmetric. - Sharpen wording: name ErrorOr's HTTP mapping concretely instead of a bare mention; describe FluentResults' reasons model in terms of its real capabilities; in the table, say multiple-error aggregation is left to the application, and that ToException() yields a structured, category-typed exception (verified: DomainException et al. carry .Error).
…ntation-navigation
- Split the long introductory paragraph into three, so the scenario's acknowledged bias reads more clearly. - Frame the named factory as the recommended usage rather than a technical requirement (DomainError.Create can be called inline), and gloss "transport" on first use. - Say the durable knowledge lives with the error's definition, not "beside the error".
- Replace the false-friend "librairie" with the standard French "bibliothèque" across the comparison page and the two pages that link to it (documentation map, FAQ). The comparison page is retitled and the inbound navigation labels are updated to match. - Format the "Outcome" transport as the `Outcome` type in the decision guide, in both the English and French comparison pages.
A map should know its own territory. Replace the three "any ... available in the current documentation version" pointers with direct links to pages that exist in the branch: - Error Taxonomy and Composition, under "understand the model"; - Integrate with structured logging, under "integrating delivery and operations"; - the Extraction and Project Discovery Reference, under "extending the documentation pipeline" and in the reference section. Also restructure for clarity: - Enrich the reference section (add the extraction reference; drop the FAQ, which is guidance, not a reference). - Add a "stuck or unsure about a decision" section gathering FAQ, Usage Patterns, When Not to Use, and the library comparison. - Present internationalization and analyzers as optional complements to writing an error rather than numbered mandatory steps. - Contrast the map with the README in the introduction. The English and French pages stay in sync.
- Say the primary pages point readers toward focused guides rather than asserting every page systematically links to them. - Frame "understand the model" for an individual reader too, not only for a team defining project-wide conventions. The English and French pages stay in sync.
Reefact
marked this pull request as ready for review
July 15, 2026 23:44
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
2 participants
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 completes the documentation-improvement series with a concrete, neutral comparison against other error-handling libraries and a bilingual documentation map organized by reader intent.
Type of change
Changes
Testing
dotnet build FirstClassErrors.slndotnet test FirstClassErrors.slnFirstClassErrors.Analyzers.UnitTests)No build or test command was run because this PR changes Markdown documentation only. The comparison was reviewed against the current public ErrorOr and FluentResults documentation, and the branch diff and documentation links were reviewed manually.
Documentation
doc/updateddoc/README.fr.md) updated if user-facing behavior changedThe French counterpart of every changed or added English page is included. The root README files are intentionally unchanged in this independent PR because the earlier documentation batches introduce additional focused pages on separate branches; the new map uses only primary entry pages and can be linked from the final merged README without creating temporary broken links.
Related issues
None.