tech.guitarrapc.cóm

Technical updates

PowerShell 本を出版するまでの反省

PowerShell本を書いたのですが、当然多くの反省があります。

tech.guitarrapc.com

どれも自分の苦手とすることへの直視を求められるのでメモしておきます。

プログラミング系の本を書くときの参考になれば幸いです。

目次

そもそもなぜ本を書いたの

本を書く動機はいろいろなケースがあると思います。

私の場合、本を書きたいというより「本を通してPowerShell に感じる悩ましいと思わせる部分への一定の解消を図りたい」という思いで書きました。 結果は読者のみぞ知るので分かりません。

もともと私が持っていたPowerShellの課題に「学習コストが高すぎる」というのがあります。ただコマンドを実行するだけならいいのですが、適当に書いたスクリプトがよくわからないけど動かない、意図した結果にならないというのは、今でもそこかしこで見ます、聞きます。「PowerShellは学の大変だから触るのすら忌避する」という声をよく耳にするたびに、ナルホドタシカニと感じてきました。

自身、今まであったPowerShellの本で自分の知りたいことが知れず、手さぐりで学んできた部分が大きいです。PowerShell InActionは良い本ですが、この本でPowerShellに感じる苦しみは解消されませんでした。配列やスコープは理解できず、モジュールも何それです。英語出版本も10冊近く持っていますが、どれもスコープは小さく、知っている前提、レール上で使う前提でした。そのため、自分がやりたいことをやるためにPowerShell Utils などの小ネタ置き場を作ったり、モジュールを公開し、シェル芸を書き、一つひとつ学んだことを記事にしたり、MSDNやDocs が更新されると読んで新しいことを学び、誤りに気付き、理解のすり合わせを行う繰り返しをしています。

この状況は、ブログを書いていても「調べることができる人」という条件がつくためリーチ層が限定されます。そこで、編集者さんからお話をいただいた時に、リーチできない層に対して、次のニーズを満たすものを伝えるものがないなら書こう、それを書けせてもらえるなら書くというのがこの本の根幹です。

  • 学ぶコストを減らすため一冊で全然書いたことがない人、書いたことあるけどただコピーしただけ、ちょっと書いてる、普段から書いてる、めっちゃ書いているをある程度網羅する *1
  • とりあえずこれ読めば罠とか理解して回避方法もわかる
  • どう書けばいいかのサンプルが分からない状況にサンプルを提供する
  • 後でわからない時にでも読みなおせる
  • 途中まで読んで、分かるようになったときに先も行ける、

執筆期間

本どれぐらいで書いたのか度々聞かれます。だいたい2カ月です。

内訳は、1-2月の深夜、3月半月 + 4月半月 + 5月半月。 3月以降は仕事がないので一日12-18時間ぐらい当ててたようです。*2

仕事をしながら書ける人、心底尊敬します。気持ちの切り替えがポイントなのですが、難しいと感じました。

反省点

いずれも自分への甘えと見込みの甘さが露呈することになります。

書き始めるまでの重さ

最も反省するべきは、エンジンがかかるまでが遅いという悪い癖が露骨に出て足を引っ張りました。

本は書きたい、締め切りもあり書かなきゃなのですが、どうしてもVS Codeを開くまでの気持ちを持っていくのがムズカシイ時期がありました。 仕事をしている時の深夜、締め切りを意識していない時、意識し始めた時それぞれでまんべんなくあるので、私の欠点です。

対策

  • 時間を消費していたことをしようとしたときに閉じる (主に読書とYoutube が大きかったように思います)
  • 音楽を決める

もともとYoutubeでバックグラウンドミュージックを書けて、プログラムや記事を書く習慣があります。が、この時期に動画の音楽を流すことをしてたせいで動画を見る、映像に注目する悪い癖がつきました。そのため、Youtubeで一日の時間が溶けることもあり、開くのをやめました。小説は気分転換がずるずると、パターンだったのでそもそも開かないことにしました。

音楽は意識を集中させるために使っているので、実はなくても書けるのが分かっています。事実、音楽が途中で切れてても一日中書いていることも多いです。しかし音楽を使って意識を書く方に集中させる、書くことの環境であると自己暗示書けることに使っているためある方がスムーズに書き出します。そこで、Playlistを決めて、エンドレスに流すことで、音楽と執筆を結びつけました。主に "Put Your Hearts Up"が多かったです。

一日の書ける量

色々な方が書かれていますが「ブログと全然違って全然書けない」です。「適当を書けない」という当然の事実がびっくりするぐらい書けなくしました。まさか一日10P程度も書けないことがあるとは思いませんでした。*3結果、締め切りを延長したにも関わらず直前まで修正していたので、本当に余裕ありませんでした。

文章構造も書きにくさの原因でした。私が読書をしていて一番嫌いなのが、事前に知らないことを先に出して後から説明されることです。*4知らない概念を先に出した場合、思考のジャンプが生じるためかなり嫌っています。今回、自分で書いていて発生したため、文章構造を5回書き換えています。始めに目次とプロットを書いていても発生したので、レビュー時に考えることにしてある程度割り切りました。*5

私は、RE:View を使っていたのですが、初めてのRE:Viewによる書きにくさは一週間程度ありました。その後もプレーンテキスト書くよりもRE:View書式当てることの手間はありますが書ける量はそこに起因していないように思います。

対策

  • プロットを細かく出す
  • 今日はここまでという目標スケジュールを紙に大きく書いて共有しました
  • 文章構造をブロックごと入れ替え、つなぎはレビューまで割り切る
  • 事実に基づいて淡々と書いてから肉付けをする

プロットと一日に書けるページ数(10P-50P)をある程度同期させることでスケジュール管理しました。同期が崩れると進捗が不明で完了が未定になるので、これはマストな約束事として自分の中で持てました。

目標の達成度を見える化することで、プレッシャーを外部から与えてもらいました。案の定レビュー時に入り乱れて機能しなくなったのですが、文章を書いている分には、自分のダメ具合が露呈するのでオススメです。

「文章構造を考えながら書く」のと「ブロックごとのテーマについて書く」では、難易度がけた違いです。ブロックごとのテーマに集中するのは非常に簡単で、ブログが書きやすい理由はこのテーマが決まっていることにあります。本を書くときに「全体の構成を考えながら書く」のは、章ごとに分離しても難易度が高いため辞めました。ブロックごとに書くようにしたことでかなり書きやすくなりました。

文章に肉付けされていると前後の文脈が作られてしまい、ブロックごとの移動をする修正が困難です。淡々とした文章で書いておいて、文脈を整えるようにすると移動が楽になりました。文章を書く基本なのでしょうが、なかなか気づけず無駄に時間を使いました。

表現の難しさ

網羅するというのが本当に厳しく、文言の表現でも悩みがずっと解消できなかった部分です。そのため、文章に日本人じゃないんじゃないか、というレビューはそうですねと感じます。誤字脱字の多さもレビュー時点から指摘を受けています。編集者さんの修正が結構入っているのですが、それでも誤字脱字あるので元がまずいのは明らかです。

対策

  • もっとすっきりした文体にする

最終版でも、文体がくどいためすっきりしていいと感じます。

ページの超過

当初、編集者さんと合意した目標ページは400Pです。蓋を開けると624Pでした。まさかの224P超過、いいわけもありません。Goを出してくださった編集者さんにはお礼しかありません。

対策

  • プロットをきっちりねる

中盤にプロットを練りなおした時に誤差が小さくなったことからも、当初の見込みの甘さは明らかです。 この影響は多きく、最も面白いであろう5章がページ相対量が少なくなっているのは完全な失敗でした。

サンプルコードの担保

自分が読んでてほしいので、サンプルコードをふんだんに入れましたが、その動作確認をWindows PowerShell / PowerShell Core (Windows / macOS / Linux) の書く環境で行うことが思った以上にコストになりました。

対策は次の通りです。

  • サンプルコードに依存する文章だけコードの変更がないように気を配り、他はコード修正を前提にする

本質的には、マトリックスでクロスプラットフォームテストをかけるのがいいのですが、執筆中にテストを用意するのが過負担でした。誰かにお願いすればよかったです。

兼業はできない

1-3月を通して日中仕事している時に夜書くのは私にはムリでした。1章は深夜1カ月 + 3月の数日を当ててようやく書きましたが、非常に苦しかったことを覚えています。

また、退職と無職期間がまるまる執筆で費やされたのでのびのびできなかったのが悔やまれます。2018年の最優先課題だったのでシカタナイのですが、無駄に溶かした時間を考えると反省しかないです。

編集者との文章共有

GitHub + RE:View で書いていたのですが、編集者さんの印刷用割り付けとGitHub が連動できなかったことが悔やまれます。 編集者さん側の文章をGitHubにわざわざ反映してもらう必要があり、2度手間どころではありませんでした。 RE:View を用いたにも関わらず、RE:View で書籍製本もできなかったので、いろんな意味で悔いが残ります。

対策

  • 編集者さんに合わせる重要性を理解してもらう
  • 編集者さん側の文書フォーマットに合わせるなり、完全に同一フォーマットを用いる
  • Diff を活用する

なに使っていますか? これでいいですか? というすり合わせをはじめにやっていますが、こちらの自由でいいといわれた時に、この問題を予見できなかったのは自分の未熟を感じます。

手間をなくすためには、同一フォーマットを使うのが最善です。これはWeb寄稿ではなかった課題で、結構難しいと感じました。GitHub + RE:View or Markdown が標準になると、私は嬉しいですがどうなんでしょうか。

Diff を活用は実はしていたのですが、フォーマットが同じでないので漏れをお互いにシステム的になくすことができなかったのはムリゲー感じます。

重版予定は?

今はありません。本が分厚く余り出ない一方で、電子書籍が良く売れているということで鈍器なんでしょう。

もし重版が出るなら誤字脱字や表現上の修正、PowerShell Core 6.1/6.2の対応をしたいのですが、予定は未定です。

*1:この時点で欲張り

*2:ぜんぜん遊べておらず仕事よりハードでした。

*3:ブログの文章換算で甘く見てました

*4:言葉を置き換えて先に出すのはいい

*5:案の定レビューで指摘を受け、粛々と直しました