Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: separate tutorials from how-to guides #1027

Closed
wants to merge 1 commit into from
Closed

docs: separate tutorials from how-to guides #1027

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion website/docs/tutorial-basics/_category_.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,6 @@
"position": 2,
"link": {
"type": "generated-index",
"description": "Hands-on learning experiences for API specification fundamentals"
"description": "Learning-oriented guides that teach API specification fundamentals through hands-on experience"
}
}
17 changes: 9 additions & 8 deletions website/docs/tutorial-basics/create-an-api-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,12 +4,13 @@ sidebar_position: 1

# Create an API Specification

Use `@api-ts/io-ts-http` to define a standalone **API specification** in TypeScript.
Learn to define a standalone **API specification** in TypeScript using
`@api-ts/io-ts-http`.

## What problem does `io-ts-http` solve?
## Understanding API Contracts

Web services use an [API] as a contract to describe how _clients_ should communicate
with _servers_.
Web services use an [API] as a contract to describe how _clients_ communicate with
_servers_.

When a server receives a request from a client, the server needs to answer a few
questions before it can begin fulfilling that request:
Expand All @@ -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**,
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"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

removing the burden of semantic analysis from business logic.

[api]: https://en.wikipedia.org/wiki/API

Expand All @@ -41,7 +42,7 @@ $ mkdir api-ts-example
$ cd api-ts-example
```

In your new directory, create a `package.json` file:
In the new directory, create a `package.json` file:

```json package.json
{
Expand Down Expand Up @@ -91,7 +92,7 @@ export const API = apiSpec({
});
```

Compile your API specification with:
Compile the API specification with:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


```
$ npm run build
Expand Down
16 changes: 9 additions & 7 deletions website/docs/tutorial-basics/create-an-http-client.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,14 +4,16 @@ sidebar_position: 3

# Create an HTTP Client

Learn how API specifications enable type-safe communication between clients and servers.

`io-ts-http` API specifications are not coupled to any particular HTTP client. `api-ts`
provides helper libraries that wrap your favorite HTTP client and use the TypeScript
type-checker to ensure type-safe communication with a server implementing an
provides helper libraries that integrate with various HTTP clients and use the
TypeScript type-checker to ensure type-safe communication with a server implementing an
`io-ts-http` specification.

## Create a type-safe HTTP Client from an API specification
## Building a type-safe HTTP Client
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

quibbles:

  • Microsoft's style guide says headings should use sentence case (only capitalize the first word), so client should 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This replaces 1 word with 3, which works against minimalism and brevity

(highlighted):

```json package.json focus=10,12,17
Expand All @@ -37,7 +39,7 @@ As before, first edit your `package.json` file to add our new dependencies
}
```

And install them by running:
Install them by running:

```
$ npm install
Expand Down Expand Up @@ -71,14 +73,14 @@ main();

Notice the inferred type of `response.body`.

Compile and run `client.ts` (make sure your server is still running!):
Compile and run `client.ts` (ensure the server is running):

```
$ npm run build
$ node ./client.js
```

You will see output like
The output will be:

```
Response is: Hello, world!
Expand Down
17 changes: 8 additions & 9 deletions website/docs/tutorial-basics/create-an-http-server.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,19 @@ sidebar_position: 2

# Create an HTTP Server

An API specification is only useful when clients and servers adhere to its rules.
Learn how API specifications enable type-safe communication between clients and servers.

`io-ts-http` API specifications are not coupled to any particular HTTP server. `api-ts`
provides helper libraries that wrap your favorite web server and use the TypeScript
type-checker to ensure your server implementation satisfies the target API
specification.
provides helper libraries that integrate with various web servers and use the TypeScript
type-checker to ensure server implementations satisfy the target API specification.

## Create an HTTP server implementing your API specification
## Building a server with your API specification
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


[express]: https://github.com/expressjs/express

First, edit your `package.json` file to add a few new dependencies (highlighted):
First, edit the `package.json` file to add a few new dependencies (highlighted):

```json package.json focus=7,9,13,14
{
Expand All @@ -39,7 +38,7 @@ First, edit your `package.json` file to add a few new dependencies (highlighted)
}
```

And install them by running:
Install them by running:

```
$ npm install
Expand Down Expand Up @@ -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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I personally favor the source text here too, citing 2nd person MSGW advice


```
$ curl localhost:3000/hello/world
Expand Down
18 changes: 10 additions & 8 deletions website/docs/tutorial-basics/render-an-open-api-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,19 +2,21 @@
sidebar_position: 4
---

# Render an OpenAPI specification
# Render an OpenAPI Specification

Learn how to generate OpenAPI specifications from `io-ts-http` API definitions.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.


An `io-ts-http` specification contains a superset of an [OpenAPI] specification.
`api-ts` provides `@api-ts/openapi-generator` to produce an OpenAPI specification from
your `io-ts-http` API specification. This lets you plug your API specification into the
existing OpenAPI ecosystem to HTTP clients for languages other than TypeScript. These
clients won't be as ergonomic or type-safe as an `api-ts` HTTP client.
an `io-ts-http` API specification. This enables integration with the existing OpenAPI
ecosystem to generate HTTP clients for languages other than TypeScript. These clients
won't be as ergonomic or type-safe as an `api-ts` HTTP client.

[openapi]: https://www.openapis.org/

## Use `openapi-generator`
## Working with `openapi-generator`
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Prefer the source text, present tense, active voice, minimalism, 2nd person rule

(highlighted):

```json package.json focus=15
Expand All @@ -41,13 +43,13 @@ As before, first edit your `package.json` file to add our new dependencies
}
```

And install it by running:
Install it by running:

```
$ npm install
```

The `openapi-generator` requires our TypeScript compiler settings to be specified in a
The `openapi-generator` requires TypeScript compiler settings to be specified in a
`tsconfig.json` file, so create one like this:

```json tsconfig.json
Expand Down