今書いてるjs-primerをどのように書いてるかのメモ書きです。

今、基本文法のPromiseについてを書いています。

この章は2017年9月28日のミーティングで事前に次のような流れになることを確認していました。

  1. エラー/try…catch構文 @laco担当
  2. Promise/Async Function @azu担当

すでにエラー/try…catch構文の章は@lacoによって書かれています。

やっとユースケース: Todoアプリも終わったので、自分の担当であるPromise/Async Functionについてを書き始めました。

書く流れ

ここ最近はまずOUTLINE.mdというファイルを、各章と同じディレクトリに配置しています。

たとえば、関数とthis · JavaScriptの入門書 #jsprimerでは次のようにファイルを配置していました。

function-this/
├── OUTLINE.md
├── README.md

このOUTLINE.mdには、その章の目的やアウトライン、書くこと、書かないことをメモ書きをしているファイルです。 書いてる途中でなんでも編集するので、AlfredでOUTLINE.mdを検索してすぐエディタで開けるようにしています。（また、OUTLINE.mdだけをmasterへ直接同期するスクリプトを定期的に叩いています)

targetDir="$HOME/.ghq/github.com/asciidwango/js-primer-outline"
cat << eob
<?xml version="1.0"?>
<items>
eob

for item in `find "${targetDir}" -name "OUTLINE.md"`
do
cat << EOB
<item uid="$item" arg="$item" valid="YES" autocomplete="$item" type="file">
<title>${item/${targetDir}\///}</title>
<subtitle>Open '${item}'</subtitle>
</item>
EOB
done
echo "</items>"

まずはこのOUTLINE.mdに目的やどういう要素が必要かをざっとアウトラインで書き出していきます。 大体書いてるとよくわからない仕様が出てくるので、必要に応じてECMAScriptの仕様書を読んでいます。

今回のPromiseでは、まず紹介する項目というところで、PromiseのメソッドやAsync/Awaitについてを考えていたようです。

書き出していると、Promiseの前に非同期処理とは何かという話が必要で有ることに気が付きました。 この章までに一切に非同期処理が出てきていないし、この書籍は初級者〜中級者ぐらいのレベルを対象にしているので、非同期処理を知らない人もいるからです。 （プログラミングをやったことはあるという前提ですが、言語や作るものによっては非同期処理が全くなくてもかけてしまうため）

なので、まずは非同期処理、そしてエラーファーストコールバック、それから本来の目的だったPromise、最後にAsync Functionという流れになることが見えてきました。

ここで大まかな流れを全体的な流れとして書いていたようです。

次に実際にどう書くかを考えて仮のアウトラインを書き出しています。ここで一緒にどういうサンプルコードが必要になるかも考えています。(今回はいまいち浮かばなかった)

ここでアウトラインは大体見えてきて、後は実際にどう書くかや仕様の細かいところがわからない感じになってきました。 なので、アウトラインをずっとやっていてもしょうがないので、まずは”非同期処理”についてを書き始めました。

書いているとよりはっきりとしたサンプルコードが必要になるので、サンプルコードも書きながら文章を書いています。 js-primerではMarkdown中に書いたJavaScriptのコードもDoctestできるできるので、文法紹介レベルのコードではそのまま文章にテストを一緒に書いています。

式 // => 値と書くと式の評価結果が値になることをテストしている。

```js
const a = 42;
console.log(42); // => 42
```

詳しい仕組みはContribution Guideに書いています。

本文を書いてまたOUTLINE.mdが流れに沿っているかを確認します。 このときにアウトラインに書いているけど本文では書かなかったものをどうするかを考えます。 実際に不要なら、アウトラインで”未使用”などのリストに移動させて、これは意図的に書かなかったということを残しておきます。 アウトラインのような一時的なデータは、アウトラインから消すよりも使わなかったと残しておくほうが後から見なおすときに便利です。

これはアウトライナー実践入門あたりの影響を受けたアウトラインの使い方をしています。

また、アウトラインと本文の流れがあってないなら、どちらかがおかしいので揃えていきます。（厳密に揃えるというよりは、セクションごとの流れがあってればいいぐらいの感じ）

後は、このアウトラインを整えて、本文を書いてアウトラインを見直してを繰り返して章を作る感じです。

また最近文章の間違いに気づいたら · JavaScriptの入門書 #jsprimerという章を作りました。 全くバグがないプログラムはないのと同様に、全く間違いのない技術書は存在しないため、js-primerでバグを見つけたときにどうすればいいかという話を書いたものです。

Contribution Guideにもっと詳細に書いていますが、どのようなときにIssueやPRを立てればいいのかについてを書いています。

もし、js-primerを読んでいて、間違い（typoから技術的な間違い、読みにくさ）などを見つけたら、ぜひこの章を読んで行動してみてください！