docs(typed-express-router): Refactor documentation into Diátaxis Reference section #1040
Conversation
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
…ence section
This commit refactors the documentation for the `@api-ts/superagent-wrapper` package, migrating technical details from the main README into a dedicated, structured Reference section following the Diátaxis framework.
**Motivation:**
The previous documentation, while providing a getting started guide, lacked a formal, easily navigable technical reference for the package's core components. Users needing specific details about function signatures, parameters, return types, or the structure of the generated API client had to infer them from the narrative guide and examples. Adopting the Diátaxis framework provides a standardized, clear structure for technical information, improving user experience and maintainability.
**Changes Implemented:**
1. **Established Diátaxis Reference Structure:** Created a new documentation structure under `docs/reference/superagent-wrapper/` specifically for reference material.
2. **Component-Based File Organization:** Split the reference documentation into multiple MDX files, each focusing on a distinct component or concept:
* `index.mdx`: Provides an overview and entry point for the `@api-ts/superagent-wrapper` reference section.
* `superagent-request-factory.mdx`: Contains the detailed technical reference for the `superagentRequestFactory` function.
* `supertest-request-factory.mdx`: Contains the detailed technical reference for the `supertestRequestFactory` function.
* `build-api-client.mdx`: Contains the detailed technical reference for the `buildApiClient` function.
* `api-client.mdx`: Provides a comprehensive description of the structure of the `ApiClient` object returned by `buildApiClient`, including its operation methods, the `PreparedRequest` methods (`.decode()`, `.decodeExpecting()`), and the structure of the `ApiResponse`/`SpecificApiResponse` objects.
3. **Content Migration and Enhancement:** Extracted technical details and examples from the original README and rewrote them into formal reference documentation. This includes:
* Precise descriptions of each function's purpose.
* Clear representation of function signatures (including conceptual type definitions where applicable).
* Detailed breakdown of parameters and return values.
* Technical explanation of the generated `ApiClient` object's structure and behavior.
* Explicit documentation of the `.decode()` and `.decodeExpecting()` methods and the response objects they return, including notes on type narrowing.
**Benefits (Impact on Users):**
* **Improved Findability:** Users can now directly navigate to the specific component they need information about (e.g., `buildApiClient`, `.decode()`).
* **Enhanced Clarity:** Provides clear, unambiguous technical descriptions separate from narrative guides.
* **Better Organization:** Structured according to a well-regarded documentation framework (Diátaxis).
* **Increased Detail:** Offers more explicit information on signatures, types, and the behavior of the generated client than was previously available.
* **Consistency:** Aligns the documentation approach with other packages potentially using the same framework (e.g., `@api-ts/io-ts-http`).
This restructuring significantly improves the quality and usability of the technical documentation for `@api-ts/superagent-wrapper`.
…rence section
This commit significantly restructures and enhances the documentation for the `@api-ts/typed-express-router` package by adopting the Diátaxis framework and creating a dedicated, multi-file Reference section.
**Motivation:**
The previous documentation, primarily located in the README, mixed introductory guides with technical details. This made it difficult for users to quickly find precise information about specific functions, types, or configuration options without reading through narrative content. A formal Reference section, following Diátaxis principles, provides a much clearer, more accessible, and maintainable structure for technical documentation.
**Changes Implemented:**
1. **Diátaxis Reference Structure:** Established a dedicated directory (`docs/reference/typed-express-router/`) for technical reference material, separating it from other documentation types (like Tutorials or How-To Guides, which might exist elsewhere).
2. **Component-Focused File Organization:** Divided the reference documentation into distinct MDX files, each dedicated to a specific component or concept of the library:
* `index.mdx`: Serves as the entry point and overview for the typed-express-router reference section.
* `create-router.mdx`: Details the `createRouter` function.
* `wrap-router.mdx`: Details the `wrapRouter` function.
* `typed-router.mdx`: Describes the `TypedRouter` object itself, including its typed route methods (e.g., `.get`, `.getUnchecked`) and middleware handling (`.use`).
* `request-response.mdx`: Explains the augmented `req` (with `req.decoded`) and `res` (with `res.sendEncoded`) objects provided to route handlers.
* `configuration.mdx`: Documents the global (`TypedRouterOptions`) and per-route (`RouteOptions`) configuration, including error hooks (`onDecodeError`, `onEncodeError`), the post-response hook (`afterEncodedResponseSent`), and `routeAliases`.
* `typed-request-handler.mdx`: Describes the `TypedRequestHandler` helper type for improved type safety in handler definitions.
3. **Content Migration & Refinement:** Technical information previously embedded in the README's "Usage" section has been extracted, expanded, and reformatted into precise reference documentation within the new structure. This includes:
* Clear function/type signatures.
* Detailed descriptions of parameters and return values.
* Explicit explanations of component behavior (e.g., checked vs. unchecked routes, hook triggering conditions).
* Code examples focused on illustrating the specific component being documented.
**Benefits (Impact on Users & Maintainers):**
* **Improved Discoverability:** Users needing technical details about `createRouter`, `req.decoded`, configuration hooks, or other specific features can now find dedicated pages quickly.
* **Enhanced Clarity & Precision:** Technical specifications are presented directly and unambiguously, separate from introductory narratives.
* **Better Maintainability:** Isolating documentation for each component makes future updates easier and less error-prone.
* **Standardized Structure:** Adopts a recognized documentation pattern (Diátaxis), improving consistency potentially across multiple related packages.
* **Increased Comprehensiveness:** Provides more explicit detail on the library's features and types than previously available in the consolidated README.
This refactoring represents a significant improvement in the quality, usability, and maintainability of the `@api-ts/typed-express-router` technical documentation.
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.
This PR significantly restructures and enhances the documentation for the
@api-ts/typed-express-routerpackage by adopting the Diátaxis framework and creating a dedicated, multi-file Reference section.Motivation:
The previous documentation, primarily located in the README, mixed introductory guides with technical details. This made it difficult for users to quickly find precise information about specific functions, types, or configuration options without reading through narrative content. A formal Reference section, following Diátaxis principles, provides a much clearer, more accessible, and maintainable structure for technical documentation.
Changes Implemented:
docs/reference/typed-express-router/) for technical reference material, separating it from other documentation types (like Tutorials or How-To Guides, which might exist elsewhere).index.mdx: Serves as the entry point and overview for the typed-express-router reference section.create-router.mdx: Details thecreateRouterfunction.wrap-router.mdx: Details thewrapRouterfunction.typed-router.mdx: Describes theTypedRouterobject itself, including its typed route methods (e.g.,.get,.getUnchecked) and middleware handling (.use).request-response.mdx: Explains the augmentedreq(withreq.decoded) andres(withres.sendEncoded) objects provided to route handlers.configuration.mdx: Documents the global (TypedRouterOptions) and per-route (RouteOptions) configuration, including error hooks (onDecodeError,onEncodeError), the post-response hook (afterEncodedResponseSent), androuteAliases.typed-request-handler.mdx: Describes theTypedRequestHandlerhelper type for improved type safety in handler definitions.Benefits (Impact on Users & Maintainers):
createRouter,req.decoded, configuration hooks, or other specific features can now find dedicated pages quickly.This refactoring represents a significant improvement in the quality, usability, and maintainability of the
@api-ts/typed-express-routertechnical documentation.