docs: add Diátaxis taxonomy labels to documentation categories #1026
Conversation
- Update sidebars.js with explicit category definitions - Modify how-to guides category description - Create reference/explanation category scaffolding - Align documentation structure with Diátaxis framework
- Remove invalid documentation_type field from category configs - Update category descriptions per Diátaxis framework - Fix Tutorials/How-Tos/Reference/Explanation categories - Align with Docusaurus schema requirements
There was a problem hiding this comment.
@youngjungithub This duplicates content between the how-to guide and explanation. I've heard our technical writers mention how this can increase the maintenance burden, because now we have to keep two copies of the same data in sync over time.
Is this intentional, or do you have any ideas on how we can duplicate only the essential information?
There was a problem hiding this comment.
Yes it is intentional. To minimize maintenance burden we:
- Keep procedural steps in How-To Guides
- Store explanatory context in shared components
- Use cross-references instead of duplications
There was a problem hiding this comment.
How does that translate to a plan for this document? https://github.com/BitGo/api-ts/blob/audit-docs/website/docs/how-to-guides/parsing.json-strings.md
There was a problem hiding this comment.
This is the plan I have:
parsing.json-strings file
## Implementation Steps
+ [Why this pattern works](/explanation/parsing-codec-chaining)
### 1. Chain decoders for type safety
- Existing code example -
```typescript
import * as t from 'io-ts';
import { nonEmptyArray, JsonFromString, NumberFromString } from 'io-ts-types';
import { httpRequest, optional } from '@api-ts/io-ts-http';
// Define the Filter type for the JSON string
const Filter = t.type({
category: t.string,
tags: t.array(t.string),
price: t.type({
min: t.number,
max: t.number,
}),
});...Example continues......
parsing-codec-chaining file
# Type Safety in I/O Decoding
I am going to ask Designers to draw up a codec chaining diagram and post it here.
## Design Rationale
Though we know headers, URL parameters, and query parameters will be received as a
`string` or `string[]` value, due to a limitation in api-ts..... Continue...
but need to decode it with a codec that can only decode a narrower type. This pattern is
called codec chaining.
## Tradeoffs
- **Pros**: Enables gradual type refinement
|
🎉 This PR is included in version @api-ts/typed-express-router@2.0.0-beta.1 🎉 The release is available on npm package (@beta dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/express-wrapper@2.0.0-beta.1 🎉 The release is available on npm package (@beta dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/typed-express-router@1.1.14 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/express-wrapper@1.0.34 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/superagent-wrapper@1.3.4 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
|
🎉 This PR is included in version @api-ts/openapi-generator@5.8.0 🎉 The release is available on npm package (@latest dist-tag) Your semantic-release bot 📦🚀 |
2 participants
Ticket