今回の本の方針・目次

[makenowjust]

技術書典4では「Crystalの入門書」のようなものを頒布したいと考えています。
これは、今までの本は実質的にCrystalのtips集のようになっていたのですが、そもそもCrystalのことをよく知らないのにtips集を最初から買っていく人はなかなかいないだろう、ということを技術書典3やコミケへの参加で感じたためです。
もちろん部数を捌くことが重要なのではなく、即売会を通じてCrystalの知名度を高めることが参加の目的だとは思っているのですが、手元に置いてもらえた方が強く記憶に残せるはずです。
また、本の内容も三回も続けると各著者のネタが枯渇してきて、初回・二回目と比較すると全体的な分量が少なくなっています。なので、一度まとまった内容の本を作ることで知識を整理できるのではないかと思います。

このissueでは次のことを議論・確認したいと思います。

• 本の内容は「Crystalの入門書」で良いか？
• 本の大まかな見出しと、その内容を決める。
• 執筆者の募集。
• どの部分を担当するかを決める。

また、参加する人はまずこのissueのコメントで宣言してください。
その際にどの部分が書けそうかも一緒に教えてもらえるとありがたいです。

---

(この辺りからは適宜更新します。)

今のところ考えている目次です。

1. はじめに(10ページくらい？)
   • Crystalとはどのような言語か(「Ruby並に書きやすくてC並に速い」など)の説明。
   • LLVM, Rubyとかも少し説明が入るといいかも。
   • この本がどのバージョンのCrystalを前提にしているかもここに入る。
   • Crystalの情報を知るためのリンク集。
     • Crystalの公式サイトの説明。
     • gitterとか、crystal-jpのSlackとか。
     • shardまとめたサイトとか。
2. インストール(10ページくらい？)
   • Crystalのインストール方法。
     • Macでの方法とUbuntuでの方法、Bash on Ubuntu on Windowsを使えることも説明したい。
   • エディタなどの紹介もここでする。
3. 構文(20ページくらい？)
   • Crystalの構文をRubyとかと比較しながら説明していく。
   • 基本的なプログラミングの知識は仮定してOK。(クラスとは？　オブジェクト指向とは？　みたいな説明はいらない)
   • 各構文についてサンプルコードを一つくらいの粒度。
   • 後置whileはRubyにはあるけどCrystalにはないねー、みたいな。
4. shards(10ページくらい？)
   • shardsの基本的な使い方、パッケージの作り方など。
   • fizzbuzzパッケージでも作る？←fizzbuzzだと依存が無くて微妙‥‥
   • テストの書き方もここで説明する。
5. ツール(5ページくらい？)
   • crystal tool formatとかcrystal tool expand辺り。
   • エディタとの統合も説明してほしい。
6. Web開発(20ページくらい？)
   • 最初にいくつかWebフレームワークを紹介。
   • それから、どれかのフレームワークで簡単なWebアプリケーションを実装。
     • ルーター、DBアクセス、テストなど込み込みがいいです。
7. CLI開発(20ページくらい？)
   • 簡単なCLIアプリケーションの作り方を‥‥。
   • Crystal標準のoption_parserパッケージとか、その他のサードパーティーのライブラリの使い方を説明するとか。
   • あまり考えてない。
8. 歴史(3ページくらい？)
   • @nob-suz さんに丸投げする感じにしたい。

全体で100ページくらいのつもりです。

また、他に次のようなことを考えています。

• Crystalのバージョンが上がってもコードが壊れていないか確認できる仕組みを作りたい。
  • 具体的には、コードと記事を分離して、記事からはコードをincludeする形にする。
  • コードのコンパイルや、コードに対してテストを書いておいて、CIを回す。
  • この辺の仕組みはボクが色々考えます。
• ↑の都合で、今のところ記事のフォーマットを何にするかは決めていません。pandocとかasciidocとか色々試していきたいと思います。

/cc @at-grandpa @msky026 @arcage @karupanerura @5t111111 @TobiasGSMollett @nob-suz

[makenowjust]

多分書けるの5人いるか分からないくらいなので、複数箇所書いても問題ないです。むしろお願いします。

[nob-suz]

こんばんは　4月２２日ですね　やれるところでしかできないかと思いますが、参加します

[at-grandpa]

すごく助かります！そして執筆参加します！

「Crystalの入門書」でよいか

とてもよいと思います。

技術書典3やコミケへの参加で感じたためです。

の部分でも体感されているなら、なおさらですね。

どの部分が書けるか

書きたい

• macro
  • 上記の目次にはありませんが、一つの提案として
  • 最近いろいろ触ってみたくなってきたのでモチベーションは高いです
  • ざっと思いつく内容は以下です
    • macroとは何か
    • どういうメリットがあるか
    • macroでできること
    • macroを書いていくに当たってのコツ
    • サードパーティライブラリからみるmacroの活用事例
• cliツール
  • https://github.com/at-grandpa/clim で、CLI-builderを作ってます
    • この自作builderを使って https://github.com/at-grandpa/des というcliツールをつくりました
    • brewでの配布方法も書けます
  • option_parserは使い方わかります
  • 他のサードパーティ製のライブラリは触ってみないとわかりませんが、競合調査的な意味でも触ってみたいとは思っています

書けそう

• 構文
  • 書けなくはなさそう
  • rubyとの比較はある程度できますが、かなり細かいところまでは難しそう
• shards
  • 調べれば細かいところまでは書けそう
• ツール
  • 書けそうだがページは稼げなさそう

書けなさそう

• Crystalのインストール方法
  • すごく細かい部分までは書けなさそう
  • ただインストールするくらいしかしていないので
• Web開発
  • @msky026 さんにここはぜひ！
• コンパイル/コンパイラ周りなど
  • クロスコンパイルの話やllvmなどにはちょっと弱いです

[arcage]

• 本の内容は「Crystalの入門書」で良いか？
  • 良いと思います
• 本の大まかな見出しと、その内容を決める
  • 「インストール」では crenv については触れますか？
  • マクロの説明はどこかにあったほうが良い様に思います
    • String と StringLiteral の違いとか，MacroIdの扱いとかイロイロありますし，通常の「構文」とは分けて章立てしてはどうでしょう。
• 執筆者の募集
  • お役に立てる場所があれば参加させてください
• どの部分を担当するかを決める
  • 目次を拝見したところでの自分の感触は以下の通りです

◯：できそうな気がする
△：頑張ればなんとかなるかも
×：相当厳しそう

1. はじめに（×）

   • LLVM周りの理解がかなりボンヤリしています

2. インストール（△）

   • Ubuntu環境が現状なく，検証環境の構築が必要
   • 公式ドキュメントの内容をなぞるくらいになりそう
   • エディタはほぼatomしか使ってない状況

3. 構文（◯）

   • 公式ドキュメントを叩き台にできそう
   • Rubyと比較しながらということであれば，以前書いたいくつかのエントリが流用できそう

4. Shard（◯）

   • 前々回技術書典の内容を一部流用して使えないかと
   • テスト周りについては理解の追いついていない部分を相談させてもらいながら

5. ツール（×）

   • 表面的な動作しか理解できていません
   • expandの説明をするのであればmacroの解説もあったほうが良い様に思います

6. Web開発（×）

   • Web開発の経験がなく勘所がわかりません

7. CLI開発（△）

   • サーバ管理系のツールはいくつか作り，option_parserは使用経験があります
   • サードパーティ製のshardは使ったことがなく，これから勉強になります

8. 歴史（×）

   • 0.7.xあたりからの参加ですし，そのころはまだ開発コミュニティの動向を追いかけていませんでした

[5t111111]

方針良いと思います。日本語のCrystal入門者がこれ読めば大体概要わかって使えるようになるものになりそうで 👍

じゃ、今のところ手をあげてる人のいない

1. はじめに(10ページくらい？)

の執筆に立候補します。

もし余裕があって他の人が着手してなければ他の章 (特に流れ的には 2 かな) もやります。

[makenowjust]

@nob-suz

歴史を今までの記事から取ってきて、まとめてもらえればフォーマットなどはこちらで調整します。
よろしくお願いします。

@at-grandpa

マクロについては失念していました。「構文」の次の章としてあるといいと思います。あとで修正します。

「cliツール」についてはお願いしたいです。「マクロ」の章も意欲があるなら是非。

@arcage

「インストール」でcrenvについて触れるかは @pine のやる気次第です。 @pine 氏〜。

「構文」と「shard」の辺りをお願いしたいです。

@5t111111

「はじめに」「インストール」の部分をお願いしたいです。インストールのエディタの周りの話は前回
@at-grandpa さんが書いてたと思うので、いい感じに協力してもらえたらいいと思います。

---

このコメントに書いた分担は仮なので、他に参加する人がいたら、やりたいところを言ってもらって問題ないです。

執筆環境周りは土日に色々やるつもりです。

あとは @msky026 さんに「Web開発」を担当してもらって、ボクが「ツール」の辺りを書けばひとまず埋まる気がします。

頼む〜 🙇

[masak1yu]

ちょっとサラッと見てました。
細かい点のコメントは後でしますがやるやらの宣言ではやります。
担当箇所はWeb貰います。

[5t111111]

「はじめに」「インストール」の部分をお願いしたいです。インストールのエディタの周りの話は前回「 @at-grandpa さんが書いてたと思うので、いい感じに協力してもらえたらいいと思います。

かしこまり

[makenowjust]

@arcage 原稿をビルドするシステムのテスト用に「構文」の章を書き始めてしまったので「構文」は自分が担当します。ごめんなさい。

[arcage]

了解です。
よろしくお願いします。

[makenowjust]

なんかすごい感じの原稿のビルドシステムができましたので書き始められると思います。

なんか分からないところとかバグを見つけたら適当にissueを立てるとかpull requestを投げてください。

[masak1yu]

私担当箇所の「6.Web開発」の内容ですが、恐らく基本部分はこの前の「Crystalの本3」になるかと思います。

主な変更点としては

• バージョンを0.24.1基準に
• 他のWAFの紹介
  • LuckyとAmberを軽く（事例がつくのはAmberかなと）
• Amberは良く出来てる感がありますが、かなりAmberにロックインした感があるので、この本のスコープから外れるんじゃないかと思うので今回は内容については除外する方向で
• したがってKemalの解説になります（割りと手を加えないといけない箇所がたくさんあるので入門に最適）
• テストコードを追加

ものになるかと思います。2月中めどに上げる予定です。

[5t111111]

2月中めどに上げる予定です。

すごい。

ちょっと今全く余裕なくて進められていなくて、前回の締め切りと同じくらいな感じで4/1くらいを〆切と想定して3月中には着手して仕上げたい、くらいのスケジュール感で考えてましたが、もしかしてそれじゃ間に合わないですかね…？？

[makenowjust]

原稿の締め切りは3/18いっぱいということにします。

[makenowjust]

確認できるのが今週の週末になりそうなので、それまでは細かい修正とかしてても大丈夫です。

急がせてしまったのにすみません。思った以上に忙しくて参っています。

[at-grandpa]

あまり無理なさらず！

[makenowjust]

歴史とツールは間に合わない気がするので諦めます

[makenowjust]

今のところ出てる原稿を全てまとめてみたところ、全部で140ページくらいになることが分かりました。
これはかなりのページ数で、印刷費がそこそこになります。（特に少部数だと）
これと、まだ一部完成していないことを考えて、今回は印刷しないことにしたいです。

[5t111111]

@makenowjust 僕は印刷しないのは全然構わないです。
それは技術書典で販売する/しないとは別の話ですよね？
(印刷しないにせよ電子版として売ると思ってる)

[makenowjust]

#28 に書いたのですけど、できればこの本は無料で公開したくて、電子版として売るっていうのもどうなのかな、と悩んでます。

[5t111111]

なるほど。

正直言うと、今回はブースもないですし行ける気もしていなかったので自分的にはどちらでも構わないです。

印刷/製本するのはお金だけじゃなく大変でしょうし。

ただ、(単独ブースはなくとも) やはり技術書典に出すから、というモチベーションがあって書いてきた方もいると思うので、

• 印刷/製本するか？
• 製本しない場合は電子版で売るか？
• Webで (無償で) 公開するか？

は、当然関連するとはいえ、別の問題としてわけて議論した方が良さそうと思います。

先ほど言った通り僕はそれほどこだわりがないので他の方の意見に従うということにさせてください。

[makenowjust]

とりあえず印刷までいったのでこれはクローズします。