TSKaigi 2025で「技術書をソフトウェア開発する」というタイトルで発表をしました。 スライドは次のページで公開しています。

基本的にはJavaScript PrimerというJavaScriptの入門書の話になっています。 どうやって作っていて、どうやって10年近くも更新を続けているのか、オープンソースとしての継続性などについて話しています。

関連:

JavaScript/TypeScript以外での通じる話が多いので、技術書や何かを伝える文章を書く人にとっても参考になるかなと思います。 今だと、LLMとかに投げる文章でも同様のことが言える場面も多いとは思います。

jsprimerの目的の一つに「変化に対応できるようにする」というものがあります。 これのためにjsprimerという書籍を更新しているので、jsprimerにContributeや金銭的に支援してくれる人や企業はいつでも募集しています。

p65: オープンソースに関わってもらうこと

スライド中にもありますが、現在のソフトウェア開発でオープンソースと関わらずに完結することはかなり難しいです。 そのため、入門書としての目的としてオープンソースに関わってもらうことを入れています。これはjsprimerをオープンソースで開発している理由の一つです。

オープンソースとの関わり方は色々な形があるので、jsprimerに限らずに何かしらの形で関わってみると面白いんじゃないかと思います。

GitHub Sponnsorなどでの支援も大歓迎です。

今回の発表のベースやProposalを書くときは結構LLMを使っていて、インタビュー形式でLLMに質問を考えてもらったものに回答して、そこから主張を抽出して作ってます。

スライドもLLMでアウトラインを見ながら、中身を書いていくということをやってた気がします。 昔から、アウトラインと中身を行き来して視点を変えながら書くというのをよくやっていた気がします。 アウトライナー実践入門でいうところのシェイクというやり方。

この辺は文章でもそうですが、プログラミングでも関数やモジュールという単位でアウトラインのように遠めに見ながら進めるタイミングと中身を見ながら進めるフェーズがあります。 そういった点では、文章とコードで大きな違いはないのかなと思う部分はありました。

文章やコードを読む上でも、既知から未知の方が読みやすいのは一緒で、コードの方がちょっと違うのは参照元へのジャンプ機能が充実しているという点かなと思います。 Ask the speakerでもあった気がしますが、文章を読んでる時の人間のコンテキストはかなり小さいので、jsprimerを書くときは一度に読むべきコンテキストを絞るイメージで書いています(文章ではジャンプが難しいという前提があります)。

簡単に言えば、別のページの参照を減らす(読んでるところを見てれば全部わかる)、サンプルコードを小さく保つ、パラグラフライティングで結論から書くといった話があります。 ユースケースのようなアプリケーションの章は、サンプルコードが断片的になりやすいので、それぞれのページの最後にコピペで動く完全な状態を提示することで、そこで戻って来れるような仕組みも入れています。 技術書はif文が書きにくいコード、みたいな感じで書いていくのが感覚と近いのかもしれないですね。

コードにおいては複雑度を測るのに循環的複雑度(Cyclomatic complexity)というメトリクスがありますが、 日本語だと建石評価式(自分がそう呼んでるだけ)みたいなものがあって@textstat/textstat-rule-tateish-levelとして実装したことがあります。

この辺の複雑度を低く保つことが読みやすい文章に繋がるのは同じかなと思いました。

TSKaigiお疲れ様でした！