背景

• PDF出力できるようにしたい
• CIで自動校閲できるようにしたい
• GitBookがバギーだったり重かったりするので脱したい

GitBookからDocusaurusに移行してはどうか？ · Discussion #38 · yytypescript/book

事前準備

• Vercelを課金する
• Vercelとリポジトリを連携する

準備

• GitBookをreadonlyにする。全員をReader権限に変更する。
• GitBookのGitHub Integrationを停止する。
• コンテンツを取り込む
  • docsディレクトリにMarkdownファイルを移す
    • node importFromGitbook/index.js .
    • rm -rf *.md overview reference tips tutorials writing .gitbook .gitbook.yaml
  • 移行スクリプトでMarkdownファイルの内容をDocusaurus用に書き換える
    • node importFromGitbook/updateContent.js
  • 執筆者向けの説明コンテンツを一部追加する
    • cp /Volumes/v/suinplayground/my-website/docs/writing/* docs/writing/
    • sidebar.jsに目次を追加する
  • MarkdownにPrettierをかける
    • yarn prettier:fix
  • 差分を確認しおかしなところを手修正する
  • 移行スクリプトで処理できなかった細かい修正
    • GitBook独自タグを書き換える ag '{%'で探す。
    • アンダースコアはじまりのファイルを、アンダースコアはじまりでなくする
    • バックスラッシュ
    • docs/reference/type-reuse/utility-types/record.md タイトルに謎のバックスラッシュ
  • ローカルでyarn build→yarn serveを試す

プルリクエスト

• プルリクエストを送る
• 動作確認
  • Vercel上で動作確認する
  • リダイレクトが効いているか確認する
• マージする
• 動作確認
  • /etc/hostsを書き換えて本番ドメインbook.yyts.orgをVercelに向ける
  • Vercel上で動作確認する
  • リダイレクトが効いているか確認する

公開手続き

• Vercelにカスタムドメインをセットする
• DNSの設定を変更して、book.yyts.orgをVercelに振り向ける

後処理

• GitBookの課金を停止する

その後のタスク

これらは別チケットでやる。

• #52
• #53
• #54
• #55
• #56
• #57
• その後のタスクを起票する

対象ページ

https://book.yyts.org/overview/typescript-is-not-that

コンソールの出力結果を表現するコメントの書き方を統一します。

現在次のようなバリアントがあります。

console.log(1); // -> 1
console.log(1); //=> 1
console.log(1); // 1

課題

カタカナ語の末尾長音をつけるかつけないかが曖昧だったため、執筆や表記のゆれを統一する際、textlintを設定する際にその都度考える必要があります。

解決策の方針

できるだけ決定論的に決まるようにしたいというのが、このissueの提案です。

提案する基準

基準としては、3つあります。

基準1: 長音を含め4文字以下なら、長音をつける

例: キー, アロー, エラー, カリー, キュー, コピー, フロー, オーバー, カロリー, ゲッター, サーバー, セッター, ナンバー, バリュー, ヘッダー, ベンダー, フッター, ボディー, メンバー, メーラー, ユーザー, ライター, ランナー

基準2: 長音を含め6文字以上なら、長音をつけない

5文字以上になると、末尾長音は違和感が大きくなるため、つけないほうが無難です。「エンジニアー」は変です。また、長音の情報量はほぼゼロなので、無駄は省くほうが文の文字数が節約できて読みやすいと思います。

例: アクセサリ, アクセッサ, アセンブラ, アセンブリ, エンジニア, コンパイラ, デコレータ, パラメータ, プリティア, プログラマ, プロバイダ, プロパティ, リポジトリ, コンピュータ, ジェネレータ, フォーマッタ, ボランティア, インターセプタ, コンストラクタ, トランスパイラ, コントリビュータ

ただし「インタビュー」のような例外があってもいいものとします。

合成語は各単語ごとの判定になります。例えば、「キーバリュー」を1単語扱いするとちょうど6文字で、このルールを適用すると「キーバリュ」になってしまい、これはおかしいからです。

基準3: 長音を含め5文字の場合は、ケースバイケースで自然な方を選ぶ

「エディター」vs「エディタ」だと「エディタ」のほうが多数派ですが、「コミッター」vs「コミッタ」は「コミッター」のほうが多数派です。したがって、長音を含んだとき5文字なる単語は、ケースバイケースでの判定となります。

例: エディタ, バイナリ, バンドラ, レビュア, ウォーター, カレンダー, コミッター, サイドバー, ストーリー, プレビュー, ポピュラー, メタファー, メンテナー, リテラシー

5文字のときだけ決定論的になりませんが、それ以外は決定論的になるので、基準がまったく無いよりマシだと考えます。

解決したい読者の疑問

型定義ファイルが同梱されていないJavaScript製のNPMパッケージを、TypeScriptプロジェクトで使うにはどうしたらいいですか？

JavaScriptしかないnpmライブラリがあって、vueやらReactやらAngularで使いたい時どうしたらいいですか？

回答にしたいこと

1. DefinitelyTyped

• 探し方
  • Type Search
  • npmjs.orgでTS・DTSアイコンでわかる

3. 型定義ファイルを作る
4. require

対象ページ

https://book.yyts.org/reference/builtin-api/map

章のREADMEページのサイドバーラベルが基本的に「概要」に設定されているため、次ページリンクがおかしな挙動に見えてしまう。

• ページタイトル「読んで学ぶTypeScript」の「次へ」のタイトルは「概要」
• それをクリックすると、ページタイトルは「値・型・変数」になる

README→READMEと続くときは、次ページリンクのタイトルをページタイトルに合わせたほうが良さそう。

元issue: #98

対象ページ

https://book.yyts.org/tutorials/nextjs

docs/assetsに画像ファイルがある。GitBookから移行したときに、ファイル名がなりゆきになってしまっている。

TECH PLAY女子部に参加させていただき、本書を使ってTypescriptを勉強させていただきました。（わざわざ参加者向けのメッセージやIssueのリンクを貼ってくださり、ありがとうございます！！）
とてもわかりやすく理解できました、本書を書いていただきありがとうございます！
もくもく会で読み進めるにあたって何点か気づいたことがありますので、フィードバックを書かせていただきます。

• yarn start を実行した後の yarnの抜け方 (Mac: Ctrl + C, Windows: ???) が書いてあるといいかなと思いました

• brew install nodeを実行すると最新のバージョンがインストールされますが、環境によっては最新ではなくLTSバージョンではないとyarn start時にエラーが出るようです。こちらの記事をご参照ください。
  もくもく会では

nvm uninstall v17.0.1
nvm install --lts

を実行することによって最新のLTSバージョンを入れることによってyarnが無事動きました。本書に入れるかどうかの判断はお任せしますが、ご参考までにどうぞ。

• 「読んで学ぶTypeScript」の概要ページとその次のページが少し挙動不審でした。「概要ページ」に進んだかと思いきやタイトルは「値・型・変数」ページになっており、工事中のアイコンがないにもかかわらず何も表示されていませんでした。
• こちらのページに誤字がありました。「JSONは多くのプログラミング言語で用いら（れ）ていますが」

これからも本書の更新を楽しみにしております。

TypeScriptのコンパイルエラーメッセージの表示方法が下記の3種類で書かれている。

• ``` コードブロック
• >引用
• 「かぎかっこ」

これを統一した表示方法にしたい。

対象ドキュメント

https://book.yyts.org/overview/ecmascript

対象ページ

https://book.yyts.org/tutorials/prettier

default exportやnamed exportは英単語であってTypeScriptコードの断片ではないため、「default exportでは、...」のようにコードとして表現されているところを「default exportでは、...」のように書き換える。

対象ページ

https://book.yyts.org/reference/builtin-api/error

索引:記号とキーワードにgetとsetを加えてほしいです。

get: get構文 (get syntax)

get構文は、オブジェクトのプロパティを関数に結びつけ、プロパティが参照された時に関数が呼び出されるようにします。
https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Functions/get

set: set構文 (set syntax)

set 構文は、あるオブジェクトプロパティを関数にバインドして、プロパティに設定しようとしたときに呼び出される関数に結びつけます。
https://developer.mozilla.org/ja/docs/Web/JavaScript/Reference/Functions/set

加えたい理由

初めてgetterやsetterを見た人は、「JavaScript get」や「TypeScript set」で検索すると想定されます。ところが、検索結果にゲッターセッター以外の情報が多数混じっています。getならGETリクエスト、setならSetオブジェクトなど。中にはゲッター、セッターの情報にたどり着かない人もいるかもしれません。getとsetが索引にあることで、自分が調べているget/setが何なのか明確になると思います。

「索引: 記号とキーワード」読みました！
https://github.com/yytypescript/book/blob/master/symbols-and-keywords.md

とてもありがたいです！検索が難しかったりの悩みが解決されました。
そこで、2点提案したいのですが、

提案内容

1. 日本語名と英名の両方書いてあるとありがたい
2. 参考URL（TS公式リンクなど）

2は賛否分かれそうなので、1がメインの提案です。

ex

! 非Nullアサーション（Non-null assertion operator）

コードブロックでファイル名を表現するのにコメントを使っているところがある:

```typescript
// hoge.ts
...
```

これをtitle属性を使った書き方に直す:

```typescript title="hoge.ts"
...
```

(素晴らしい本の執筆ありがとうございます！)

以下ですが、
https://github.com/yytypescript/book/blob/master/features/promise-async-await.md#promise%E3%81%A8%E3%82%B8%E3%82%A7%E3%83%8D%E3%83%AA%E3%82%AF%E3%82%B9

最後の console.log(result3) を実行すると、Promise { <pending> } が出力されてしまいます。

request1().then((result1) => {
    return request2(result1);
}).then((result2) => {
    const result3 = request3(result2);
    console.log(result3); // -> 4 -> /*** Promise { <pending> } が出力される ***/
});

おそらく以下が正しいと思われます。

request1().then((result1) => {
    return request2(result1);
}).then((result2) => {
    return request3(result2);
}).then((result3) => {
    console.log(result3)
})

ご確認よろしくお願いします。

「コンパイラー」と「コンパイラ」で表記の揺れがあったので、どちらかに統一したいです。

現状の分布

• コンパイラ: 21件
• コンパイラー: 38件

他書の翻訳状況

• TypeScript Deep Dive: コンパイラ
• Wikipedia: コンパイラ

対象ページ

https://book.yyts.org/tutorials/jest

対象ページ

https://book.yyts.org/reference/builtin-api/date

対象ページ

https://book.yyts.org/tutorials/husky

有用な資料の作成と公開に感謝します。

戻り値にも型を書く

Type 'number' is not assignable to type 'string'.

return num + 1;
~~~~~~~~~~~~~~~

説明のコンパイルメッセージを得るには、
「１」をクォートで囲む必要があるはずです。

return num + "1";

test

"14.x" だと条件が厳しいので ">=14.x" にできませんでしょうか

対象ページ

https://book.yyts.org/tutorials/eslint

コードの前後に半角スペースが入っているページがある。コード前後のスペースはスタイルシートでやるべきところなので、スペースを除去する。

数値型は `number` です <!--❌-->
数値型は`number`です <!--⭕️-->

ステータス管理はもはや「Google Docsで管理」ではなくなってきているので刷新する必要がある。

• 0004-各ページのステータス管理方法

Googleからの検索流入を見ると

• オブジェクト型は 'unknown' です。
• object is of type 'unknown'
• A function whose declared type is neither 'void' nor 'any' must return a value

といったエラーメッセージで検索してくることが結構なボリュームであります。

この解決策を書いておいてあげたほうが、困ってる人を助けられそうです。

主な流れ

1. ファイルを移動、もしくは、ファイル名を変更する
2. sidebars.jsを直す
3. vercel.jsonに旧URL→新URLのリダイレクト設定を追加する
4. yarn buildでリンク切れがないかチェックする

記号とキーワードにvoidを追加します。

1. void演算子 (JS)
2. void型 (TS)

理由

JavaScriptとTypeScriptでvoidが違う意味になります。JavaScriptはvoid演算子、TypeScriptはvoid型です。JavaScriptに詳しくない人にとっては、コード中に出てきたものがvoid演算子なのかvoid型なのか分かりにくいと思ったからです。

解決したい読者の疑問

TypeScriptプロジェクトではどこまでGitでバージョン管理したらいいですか？

回答にしたいこと

• TypeScriptプロジェクトでは.tsだけをバージョン管理すればいい。
• 生成物(.js, ソースマップ, .d.ts)をgitignoreする方法。

これをコンテンツに追加すべき理由

TypeScript初心者はコンパイラが生成するJSもバージョン管理すべきなのか分からない人もいると思うので、本書で明確な方針と具体的な設定を説明したほうがいいと思いました。

コンテンツを追加する場所

「作って学ぶ」の章。

classes.mdのprivateセクションにあるコードブロックのコメントに誤りがあります。
https://github.com/yytypescript/book/blob/master/features/classes.md

AsIs：// publicからprotectedに変更
ToBe：// publicからprivateに変更

解決したい読者の疑問

公式ドキュメントよりサバイバルTypeScriptを読むべきセールスポイントは何ですか？

回答にしたいこと

サバイバルTypeScriptには公式ドキュメントにない次の特徴があります。

• JavaScriptと並行して学べる
• 公式ドキュメントはリリースノートの内容がハンドブックに盛り込まれるのが遅れがち
• Java、PHP、Ruby、Pythonなど他の言語との比較がある
• どうすべきかのベストプラクティスが書いてある(enumの問題点、型エリアスvsインターフェース)
• 実務で本当に必要になる機能だけを厳選して取り上げている: 実務であまり役に立たないことはあえて説明していない(namespaceやテンプレート文字列型)

対象ページ

https://book.yyts.org/reference/asynchronous/promise

サイト内リンクの機能を担うpageRefを有効にしてDocusaurusを起動すると、更新が遅く、ずっと起動するとメモリ不足になるようです。

ためしに次の行をコメントアウトして動かしたらサクサクでした。

対象ページ

https://book.yyts.org/reference/asynchronous/async

解決したい読者の疑問

Reactいいねボタンのチュートリアルにyarn startする手順がありますが、これを停止するにはどうしたらいいですか？

回答にしたいこと

Control + Cを押すと止まる。

これをコンテンツに追加すべき理由

シェルコマンドの止め方が分からない人もいるということがわかったので丁寧に説明したほうがよさそうです。

コンテンツを追加する場所

Reactいいねボタンチュートリアル

関連: #98

1. constのセクションを追加する

変数宣言のconstと、const assertionのconstがあることが分かるようにする。

constはググれなくはないが、ググると変数宣言とconstアサーションが混じって出てくるので、索引にリストアップされるのが望ましいと思う。

2. 加えて、asのセクションにもas constについて触れる

as constで索引をルックアップする人対策として、asのセクションにもちょっとした記載があると良さそう。

対象ページ

https://book.yyts.org/reference/functions/callback-functions

対象ページ

https://book.yyts.org/reference/asynchronous/await

まだCIでTypeScriptのチェックをしていなかったので追加する。

• チュートリアルで環境構築でbrew install nodeするが、最近はv17が入るらしい。
• チュートリアルでReactのチュートリアルでyarn startするところがあるが、ここでv17だとエラーになるらしい。
• この問題が報告されたissue: #98

やること

• v17環境で再現し、詳細を確認する。
• エラーが起きないような手順にする。

エラーが起きないようにするには、brew installでLTSを指定するようにするか、React側の問題もあるのでReactのチュートリアルを直すか、など考えられる