docs: separate tutorials from how-to guides #1027
Conversation
Restructure documentation to maintain clear boundaries between tutorials and how-to guides following Diátaxis framework principles. Move explanatory content from how-to guides to explanation section and ensure tutorials focus on learning experiences rather than task completion.
There was a problem hiding this comment.
Requesting stronger compliance with the Microsoft Writing Style Guide on some points, particularly use of:
- present tense
- active voice
- speaking directly to your reader in second-person pronouns
| @@ -91,7 +92,7 @@ export const API = apiSpec({ | |||
| }); | |||
| ``` | |||
|
|
|||
| Compile your API specification with: | |||
| Compile the API specification with: | |||
There was a problem hiding this comment.
We follow the Microsoft Writing Style Guide, which encourages you to speak to your reader using second-person pronouns:
https://learn.microsoft.com/en-us/style-guide/grammar/person
I'm slightly hoping the framing of "your API specification" helps the reader feel a sense of attachment to their spec and the journey they're on
| @@ -26,8 +27,8 @@ questions before it can begin fulfilling that request: | |||
|
|
|||
| We'll call the first _type analysis_ and the second _semantic analysis_. | |||
|
|
|||
| `io-ts-http` lets you define API contracts to an **arbitrary degree of precision**, | |||
| removing the burden of semantic analysis from your business logic. | |||
| `io-ts-http` enables defining API contracts to an **arbitrary degree of precision**, | |||
There was a problem hiding this comment.
"enables defining" is awkward in the mouth. Another option that comes to mind is
With
io-ts-http, you can define API contracts to an arbitrary degree of precision
| `io-ts-http` specification. | ||
|
|
||
| ## Create a type-safe HTTP Client from an API specification | ||
| ## Building a type-safe HTTP Client |
There was a problem hiding this comment.
quibbles:
- Microsoft's style guide says headings should use sentence case (only capitalize the first word), so
clientshould be lowercased (oop, even the source text missed this!) - It also recommends present tense and active voice, so "Create..." is more appropriate
However, one alternative could be
Automatically generate a type-safe HTTP client
|
|
||
| As before, first edit your `package.json` file to add our new dependencies | ||
| As in previous steps, first edit the `package.json` file to add new dependencies |
There was a problem hiding this comment.
This replaces 1 word with 3, which works against minimalism and brevity
|
|
||
| ## Create an HTTP server implementing your API specification | ||
| ## Building a server with your API specification |
There was a problem hiding this comment.
Again, I think the source text is preferred here, since it is active voice and present tense, and describes more qualities of the final HTTP server
|
|
||
| We'll use [express] as our underlying web server in this tutorial. | ||
| This tutorial uses [express] as the underlying web server. |
There was a problem hiding this comment.
Use of the word "the" in this way doesn't quite sit right with me, for a reason I can't fully explain. Maybe it's a native speaker thing or maybe I'm just nuts! 😄
To try to put it into words, "the" ought to refer to something previously introduced (or I suppose about to be introduced) but we never introduce that thing, which would be "your service".
This tutorial uses express as the web server underlying your service
This tutorial uses express as its underlying web server
But again, we have the opportunity to follow the MWSG and speak directly to our audience in second-person pronouns.
| @@ -77,7 +76,7 @@ $ npm run build | |||
| $ node ./server.js | |||
| ``` | |||
|
|
|||
| Finally, submit an HTTP request to your server in a web browser or using a new terminal: | |||
| Test the server by submitting an HTTP request in a web browser or using a new terminal: | |||
There was a problem hiding this comment.
I personally favor the source text here too, citing 2nd person MSGW advice
| # Render an OpenAPI specification | ||
| # Render an OpenAPI Specification | ||
|
|
||
| Learn how to generate OpenAPI specifications from `io-ts-http` API definitions. |
There was a problem hiding this comment.
| Learn how to generate OpenAPI specifications from `io-ts-http` API definitions. | |
| Learn how to generate OpenAPI specifications from an `io-ts-http` API specification. |
|
|
||
| [openapi]: https://www.openapis.org/ | ||
|
|
||
| ## Use `openapi-generator` | ||
| ## Working with `openapi-generator` |
There was a problem hiding this comment.
Prefer the source text, present tense, active voice, minimalism
|
|
||
| As before, first edit your `package.json` file to add our new dependencies | ||
| As in previous steps, first edit the `package.json` file to add new dependencies |
There was a problem hiding this comment.
Prefer the source text, present tense, active voice, minimalism, 2nd person rule
Restructure documentation to maintain clear boundaries between tutorials and how-to guides following Diátaxis framework principles. Move explanatory content from how-to guides to explanation section and ensure tutorials focus on learning experiences rather than task completion.