docs(superagent-wrapper): Restructure documentation as Diátaxis #1039
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`.
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 refactors the documentation for the
@api-ts/superagent-wrapperpackage, migrating technical details from the main README into a dedicated, structured Reference section following the Diátaxis framework.Motivation:
Adopting the Diátaxis framework provides a standardized, clear structure for technical information, improving user experience and maintainability.
Changes Implemented:
docs/reference/superagent-wrapper/specifically for reference material.index.mdx: Provides an overview and entry point for the@api-ts/superagent-wrapperreference section.superagent-request-factory.mdx: Contains the detailed technical reference for thesuperagentRequestFactoryfunction.supertest-request-factory.mdx: Contains the detailed technical reference for thesupertestRequestFactoryfunction.build-api-client.mdx: Contains the detailed technical reference for thebuildApiClientfunction.api-client.mdx: Provides a comprehensive description of the structure of theApiClientobject returned bybuildApiClient, including its operation methods, thePreparedRequestmethods (.decode(),.decodeExpecting()), and the structure of theApiResponse/SpecificApiResponseobjects.ApiClientobject's structure and behavior..decode()and.decodeExpecting()methods and the response objects they return, including notes on type narrowing.Benefits (Impact on Users):
buildApiClient,.decode()).@api-ts/io-ts-http).This restructuring significantly improves the quality and usability of the technical documentation for
@api-ts/superagent-wrapper.