docs(typed-express-router): Refactor documentation into Diátaxis Reference section #1041

youngjungithub · 2025-04-24T19:39:44Z

This PR 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:

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).
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.
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.

…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.

vmccarty

LGTM

github-actions · 2025-07-18T17:23:39Z