docs: simplify the foundations and getting started flow#119
Merged
Conversation
The documentation method shown in the English and French readmes chained WithRule directly into WithExamples, which does not compile: the staged builder makes the diagnostics stage mandatory between the rule and the examples. Add the WithDiagnostic call, mirroring the getting started guide and the usage project. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUaMS5EHzAdQHBJzrYvKTj
Step 6 builds the solution with -c Release but ran fce generate --no-build without --configuration Release, so the generator resolved Debug assemblies that were never produced and emitted an empty catalog. Pass the configuration explicitly in both language versions and explain why it must match the build. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUaMS5EHzAdQHBJzrYvKTj
Reefact
force-pushed
the
agent/improve-docs-foundations
branch
from
66b5ea0 to
8d44bd2
Compare
A newcomer met several library-specific terms before any page defined them. Give each one a short in-place gloss at its first use, in both languages: - readme: introduce Outcome as an explicit result returned without throwing instead of the bare generic type, relate DomainError to Error, and announce the generated catalog before the code block; - getting started: explain what ProvidesErrorsFor declares, note the assumed Amount/Currency example types, and unpack the three parts of a diagnostic (cause, origin, investigation lead); - design principles: gloss the staged builder; - core concepts: gloss occurrence and inner errors, link ErrorContext at its first mention; - error taxonomy: gloss interaction direction and transience in the intro, and explain PrimaryPortInnerErrors at the first nesting example with a link to the composition rules. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUaMS5EHzAdQHBJzrYvKTj
The intro led with truisms (errors should be understood, diagnosed...) and buried the actual differentiator at the end of a sentence, using the bare Outcome<T> type with no gloss. Replace it with a direct claim (errors as a first-class domain concept, described once, reused everywhere) and break the five things the library does into short, titled blocks instead of a dense paragraph: modeling the error, handling the failure, documenting it, checking the model at compile time, and the upcoming external-input binder. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUaMS5EHzAdQHBJzrYvKTj
Add a '## One model for the whole chain' heading so the intro reads as a proper section like the rest of the readme, instead of orphan prose under the tagline. Drop the inline transition sentence the heading now makes redundant. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUaMS5EHzAdQHBJzrYvKTj
The example called InvalidAmountError.NegativeValue(...) and referenced Code.RequestRejected, neither of which exists anywhere in the codebase — invented pseudo-code that cannot compile. Replace the leading illustration with the real DateOutOfStatementPeriod primary-port error from FirstClassErrors.Usage (a genuine file-import rejection), and rebuild the composition example from real API members: the recurring InvalidAmountOperationError.CurrencyMismatch domain error nested via PrimaryPortInnerErrors, instead of the fabricated method and code. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUaMS5EHzAdQHBJzrYvKTj
The opening sentence read as discouraging (root cause unknown, so...) without saying why documenting causes is still worthwhile. State the positive reason instead: several plausible causes can usually be named even without certainty, and naming them gives investigation a starting point. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01LUaMS5EHzAdQHBJzrYvKTj
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 first documentation-improvement batch focuses on the entry point and the core mental model: it rewrites the READMEs, Getting Started, Design Principles, and Core Concepts, and introduces the new Error Taxonomy and Composition guides.
This PR deliberately does not modify the later documentation batches yet: writing errors, usage patterns, testing, operational integration, pipeline architecture, comparison, or FAQ.
Type of change
Changes
Errormodel and its transports.FirstClassErrors.Usage.Testing
dotnet build FirstClassErrors.slndotnet test FirstClassErrors.slnFirstClassErrors.Analyzers.UnitTests)No build or test command was run because this PR changes Markdown documentation only. Every code example was reviewed against the current API surface (staged builders, port and inner-error types); two referenced members that do not exist in the codebase were corrected — see Changes above.
Documentation
doc/updateddoc/README.fr.md) updated if user-facing behavior changedThe French counterpart of every changed English page is included and kept structurally aligned.
Related issues
None.