読者です 読者をやめる 読者になる 読者になる

Happy My Life

日常とか技術とか

プログラマが技術書を書くとき気をつけること

いうわけで、一冊の本がこの世に出たのだが。

本を書いている途中でいろいろと見えてくるものがあったので、そのあたりを忘れないうちに書いておこうかと。それは何かというと

本の編集に携わる人々は、編集のプロであってプロのプログラマではない」ということ。

あたり前の話ではあるのだが、制作中のテンパっているときにはつい忘れてしまうので自戒を込めて。

まず最初は、編集者さんに原稿を読んでもらって確認してもらうのだが、その時の技術的な指摘をいろいろ受けたので、つい通常のプロジェクトのメンバーと一緒に仕事を進めているような感覚に陥いってしまい、Javaプログラマでは常識的な事の説明を省いてしまうことがよくあった。

ただ、それは自分勝手な錯覚に過ぎず、そのうちプロジェクトのメンバーとやりとりするのとは違う、より理解しやすいように原稿を書く、説明するしかないというのが分かってきた…。

制作の段階でも

次に注意を払う必要があるのは、制作の段階。原稿を書籍に向けて、掲載する図などは、私が簡単に書いたモノを元に、書籍向けに書き起こしてもらうことになる。しかし、制作の方々の手にかかった段階で、解釈の違いが発生し、意図とは異なる図になることが、ままある。そして修正依頼を出す。

この解釈の違いも仕方ないかなと思っている。制作も方々も、本の制作のプロであってプロのプログラマでないわけだから。ここも図や説明を細かに入れるのがよいのかと思う。

あとは、掲載するコードもそう。"本に掲載することを意識しないコード"を原稿として渡してしまうと、これまた読みにくい状態で掲載されてしまうことになる。たとえば、Javaのコードだと、メソッド名の途中で改行されてしまうなど。そして、大量の修正依頼を…

では、どういう点に気をつけてコードを書けばよいかというと、以下のような点でないかと思うのだが。

  • タブコードは使用しない
  • 書籍における1行の文字数を確認し整形
  • コードに解説を含めるなら、その分の余白を考慮して整形

本を書く機会ってそうある訳ではないので、なかなかこういったノウハウって共有されづらい気がする。

これから技術本を書く予定がある方に参考になれば。