TypeScript in Definitelyland 発行
公開しましたよ
どうも、vvakameです。
去る12月30日、コミックマーケット87にてTypeScript in Definitelylandという冊子を頒布しました。 当日買いに来てくださった方、本当にありがとうございました！見本誌が見られている間、なかなかドキドキするものですね。 前回C86でお昼すぎから初コミケを観戦に行き、今回は初めてサークル入場で売り子(の後ろから在庫出すマン)をしました。 落ち着いて周囲を回ってみると、TechBoosterみたく在庫ガン積みしてる所が見当たらなくて、あってくぶって変なサークルだったの…？？と知りました。 Unity部さんはバウチャー販売になってて在庫の山を積んでいなかったので、賢いな…！と思いました。
頒布前から宣言していた通り、その全文を公開します。 GitHubリポジトリはこちら。 本書はTypeScriptリファレンス（Amazon、達人出版会）の既読、未読に関わらず読めるようになっています。 本書ではJavaScriptの細かい仕様については解説していません。もし、JavaScript自体の仕様について、TypeScriptと共に学びたい場合はTypeScriptリファレンスの購入をお勧めします。 TypeScriptリファレンスはTypeScript 1.0対応の書籍です。 1.0から今までの差分は、TypeScript 1.1.0 変更点とTypeScript 1.3.0 変更点を参照してください。
本書を支える技術
折角なので、本書を支える技術について言及しておきます。 技術書をこれから執筆したい、興味がある、という人に役立つかもしれません。 なお、TechBoosterの中でプロジェクト構成改善ガチ勢は多分僕だけなので僕のプロジェクトが一番研究が進んでいると思います。
最近だとPromise本やFuzoku実践入門 環境サンプルファイルあたりが技術的に頑張ってる技術書だと思うので、そちらと見比べてみても楽しいかもしれません。
ツールの選定
- Re:VIEW
- 日本の出版業界を支えるプロが利用・メンテナンスしている
- kmutoさんはトップスタジオの人なので商業（紙を含む）に持ってきたい時相談しやすそう（たぶん）
- 達人出版会のtakahashimさん
- WordなどのGitHub上でdiffが取れなかったり手で変更をmergeできない書式を使うのは嫌だ
- よーするにテキストファイルがいい
- 和文組版についてのdomain specificな事情も考慮されている
- エッジケースが色々なところにあって、何も考えずに小賢しいパッチを当てると後で「それにはこういう悲しい事情があってね…」という話を伺って涙腺が緩んだりする
- 書籍固有の拡張を行うのが比較的容易
- セットアップがダルいのが玉に瑕
- Ruby処理系とlatex(PDF出力する場合)など。
- はじめてのRe:VIEWあたりを参考にするとよい
- latexで出したいわけじゃなくてPDFが得られればそれでいいので、AH Formatter（有料）またはvivliostyleさんのプロダクトに期待するのも手
- atlasはAF Formatterを採用しているそうな（CSS組版だ！
- review.js作ってるけどやりたい事が多すぎてリソースが回ってない状態…
- 日本の出版業界を支えるプロが利用・メンテナンスしている
- GitHub
- 言わずと知れた… これを使わないとかありえない
- Issue管理とpull requestがあればまぁなんでも良い
- gh-pagesが大変便利
- gitが使えない人と組んではいけない（共著者、編集者、などなど）
- 組む場合はパッと想像した負担の5倍の苦労(または諦め)を背負う覚悟が必要
- GitHub自体については能力の高い技術者でも仕事環境や興味の方向次第ではびっくりするくらい慣れていない場合も結構あるので随時色々教えてあげよう
- 言わずと知れた… これを使わないとかありえない
- Atom
- JavaScriptで拡張可能なエディタ ということで使っている
- Re:VIEWに限ればSublime Text 2とyanzm製プラグインが一番いいと思う
- language-reviewを作っているがこれまた時間が足りない
- prh
- bundler 例
- Re:VIEWのどのバージョンを使ってコンパイルするか表すため
- 最新のリリースを使いたい場合やmaster/HEADが使いたい場合などがあるため
- grunt 例
- 使い慣れているタスクランナーならなんでもよいと思う
- わかめはRuby慣れてないのとTypeScriptバトラーなのでgrunt
- gulpは使ったことない
- pdf, epub, html の生成用タスクを準備しておく
- 本書の場合、サンプルコードのビルドチェックと原稿への埋め込み（review-preproc）なども行う
- Circle CI
- これから設定する… masterにpushがあるとgh-pagesを自動更新するやつ
- CIサービスの中で最近一番流行ってる奴
- Travis CIよりUIがこなれていて使いやすい
- テスト実行時にインスタンスが割り当てられるのが早い
- 本当を言うと、好きなDockerimageをベースにビルドできるCIサービスがあればそれを使いたい
- Re:VIEW用イメージを作ってある(使ってないけど)
- drone.ioを自分のサーバで運用すればそれが出来るんだけど自前サーバはめんどくさい
- Circle CIはビルドフェーズを細かく管理している(のでわかりやすいUIが提供できる)ので、すぐにはbaseのDocker image指定対応とかは入らなさそうな気がする
- griflet
- mhidaka
- 非常にハイエンドかつ多機能なマネージメントが行なわれる
- 自動で稼働するためこちらの要望を伝えておくだけでいい感じになる
- 編集・構成、入稿、表紙の絵・デザインの依頼、コミケ当日の搬入の手配までやっておいてくれる
- 非売品
- muo_jp
- 高性能レビュワー
- 非常に有用なアドバイスをくれる
- 〆切なんてなんのその
- 非売品
ワークフロー
書籍執筆時のワークフローをまとめておきます。 書籍執筆自体についての手引はこちら。
企画
- 本を書きたいなーという気持ちにする
- 対象読者をざっくり決める
- 目次をざっくり書く
- 今回は深さ2で設計
- これから書く予定の所はTODOとかTBDとか書いてしまい、目次が出力できるところまでさくさく作業する
- 目標ページ数をざっくり決め（られ）てしまう
- mhidakaが96Pを1ヶ月で書いてね☆ とか言ってきた時はこいつ頭おかしいな！？と思った（104P書いた）
書く
- プロジェクト構成はどっかからコピーしてくる
- 大抵一個前の著書から
- review-init とかでもいいと思う
- とりあえずまずは分量をたくさん書く
- 調査過程で役に立ったURLなどはコメントとしてしっかり残す
- 案外、後から再調査する必要が生じる事があるもの
- 自分の文章のソースがどれか追跡できるようにしておくのは重要
- 構造の変更、文章の練り上げなどは後からでも出来る！
- 特に慣れないうちはレビュアーに依るところが大きいのでまずレビューしてもらえる所まで頑張って持ってく
- 節A, B, Cの間の依存関係は最初に整理しておく
- 変数と関数、どちらを先に教えるか で文章の内容がガラっと変わる
- この依存関係を変える場合、大幅な書き直しが発生するので気をつける
レビュー取り込み
- レビュワーからの修正はpull request経由で受け取る 例
- typoの修正は直接、構成変更についてはコメントとして書く
- コメントの書式はある程度決めておく
#@# REVIEW 名前など あとから検索しやすく- 対応したものは
#@# OK REVIEW 名前などに改変する 定期的に消す - 修正後のレビュワーによる再確認は基本行わない
- そんな時間があるならもう一回通しで読んで貰ったほうがよい
- 個人毎にレビューの能力に大幅な違いがあるので気をつける
- 誤字の発見が上手い人
- わかめは誤字は脳内で自動補正がかかるらしくてあまり気がつかない…
- わかりやすい言い回しに変更するのが上手い人
- わかりやすい構成に組み替えるのが上手い人
- 特定のパターンの検知・修正が得意な人
- 誤字の発見が上手い人
- レビュワーには対象読者に近い人を必ず入れる
- 常識だと思っていた範囲が実は常識じゃなかった！みたいなことが結構多い
- その人に教える過程でどういう書き方をするのが良いか整理される場合も多い
- 人によって理解の方法は違うのでその人に特化しないように留意する
校正
- このフェーズに入ったら基本的には文章を直接触らない
- 著者がpull requestを出す側に回る
- 編集者の修正は直接masterにpushする場合が多い 例
- 変更点が気になる場合はコミットログを追って確認する
- 作業速度的に問題がないのであればpull request運用でも良いだろう
- 変更点が気になる場合はコミットログを追って確認する
- 商業の場合、編集者の言うことは基本的に鵜呑みにする
- 相手は文章のプロなので
- こっちは技術のプロなので内容の正確さの担保が最低限の責務
プロジェクト構成
- articles/
- 原稿を置く
- 昔はプロジェクトルートに置いてたけど、プロジェクトルートにあるファイルが多くなりすぎたのと、1段掘っても何も困らなかったので
- articles/images/
- 章単位でフォルダを切る Re:VIEW 1.3.0か1.4.0くらいからこれが可能 このへん
- code/
- サンプルコードは全部ここに置く
- 章・節 程度のレベルでフォルダ分けする
- 原稿中のソースコードは全部#@#mapfileでサンプルコードから展開する
- ビルドが通るコードが原稿に載っていることを保証しやすくなる
- コンパイラやライブラリのアップデート後の自動チェックが行い易くなる
- Javaのような重要ではないコードが多く入る言語の時どうするかはまだ知見がない
- maprangeを使えるようにするべき # でコメントが始まる言語じゃないといけないのが問題
- dedentも適当に処理してほしい
- TypeScriptリファレンスではmapfileの他にtslistという独自記法を導入していた
- 独自記法による飾り枠の自動判別とかも考慮していたが諸般の事情で使われなかった
- 独自記法によるTypeScriptコンパイラの制御が慣れないとわかりにくい
- 今回はサンプルコードのファイル名のルールで制御 このへん
未解決の問題
- 金銭に変換する方法
- KDP, 達人出版会, booth, gumroadなど？
- 個人的には 雑誌記事 > 紙の本 > 電子書籍 で儲かるかな？という気持ち
- 自分が頑張らなくても人様が既にレールを引いてくれてる金銭変換システムに乗るのほんと楽
- ユーザの時の便利さとはわりと両立しない
- Googleがインデックスしてくれる形式＝金にならない
- Webサイトで公開するためのノウハウ
- Re:VIEWは出版物の生成に主眼を置いているのでWebサイトで公開する形式への変換が弱い
- epubとWebサイト用HTML生成が微妙に切り離しにくい
- epubが内部的にHTMLビルダに依存しているため
- 今回はgruntタスク中でcssとlayout.html.erbの使用ON/OFFをファイルコピーで切り抜けている
- 文章間のリンク生成がめんどくさそう
- epub内でのソースコードのリフローの制御
- 今回全然調整してないです
- 検証環境、そもそも何にすればいいかわからんな？