イベント, コラム, 勉強会, 雑談

NTTPCコミュニケーションズさんの社内勉強会にDMMかき氷を送ったらLightning Talkの機会をいただきました。

NTTPCコミュニケーションズは日本の最古参のISPの1つで「高品質」なサービスを提供しているイメージがあります。
高品質を維持するには時間とコストがかかるので、なので逆にあえて品質を下げる(コントロールする)ことで、スピードを上げるのもどうでしょう?、という意図で資料作りを始めました。
資料作成に時間をかけると品質が上がってしまうので作成時間は1時間ほど。
そのため、言いたいことを言えてない感じの資料になってしまってますが、これが低品質というものです。
お目汚しになってしまいますが、記念に公開しておきます。

肝心の勉強会は、その場での手作りの食事が出たり、遠方からのゲスト発表があったり、様々なネタの飛びかう、とても雰囲気の良い勉強会でした。
お招きいただきありがとうございました。

iDC, イベント, インフォメーション, インフラ全般, ネットワーク, 製品

7月にJuniper様主催のイベントである「Juniper Cloud Builder Conference 2015」に登壇させていただいた内容を、をASCII.jpに取りあげてもらいました。

成長し続けるDMM.comのネットワーク、その変遷を担当が語る
http://ascii.jp/elem/000/001/047/1047295/
読んでいただけると、DMMの事業スピードに対応するため、Juniperのファブリック技術を用いて頑張って整理拡張をしてきた様子がわかるかと。
Juniper様主催のイベントなので、Juniper機材にフォーカスした内容になっていますが、もちろん他社の機材も使っていますよ。
機会があれば今後もいろいろと発表させていただければと思っています。

ICTSC, イベント, インフォメーション, コラム, ネットワーク, 運用管理

こんにちは!
学生ツチノコのsaiです!

今回はICTトラブルシューティングコンテスト(以下、トラコン)の一日目で出題されたネットワークの問題、スイッチ間の冗長化についてお話しようと思います。

※問題作成者ではなく大会参加者の記事となります。確実な正答ではございませんので、ご了承くださいませ。

問題のシナリオと条件

<大まかなシナリオ>
人員が増加するのでスイッチをもう一台追加することとなった。
現状、既存のスイッチと新たに導入したスイッチ間をUTPケーブル一本で接続している。
そのためか、追加されたスイッチに接続している端末のネットワークが遅くなったりと不安定である。

<条件>
1.スイッチ間の経路冗長化と通信帯域の拡張をする際、ネゴシエーションはしない設定で行う。
2.ポートはFastEthernet0/1と0/2を使用し、トランクポートとすること。

 

問題を解くに当たっての知識

・STP (スパニングツリープロトコル)

@network Cisco・アライド実機で学ぶ様  http://atnetwork.info/ccna3/stp1.html

・アクセスポートとトランクポート

ネットワークエンジニアとして様 http://www.infraexpert.com/study/vlanz2.html

・イーサチャネル

@network Cisco・アライド実機で学ぶ様  http://atnetwork.info/ccnp5/fec07.html

この問題は以上の知識と、ネットワークにおける基礎的な知識があれば解ける問題でした。

CCNAレベルを理解していれば、調べずともこの問題を解けるのではないでしょうか!

トラコンは前回か前々回まで参加する学校等の関係もありネットワーク問題の割合が多く、その難易度も高いものでした。(参加してませんが、VPNとかVPNとかVPNとか)

しかし色んな学校が参加するにあたって、問題もネットワークによるのではなくバランスの取れたものにしたようです。

 

今回の設定について

設定だけで言うと

1.スイッチA、スイッチBのFa0/2をケーブルで接続
2.ターミナルFa0/1とFa0/2にswitch mode trunkchannel-group 1 mode onを両方のスイッチに入力し適用
3.show etherchannel summayを使用し、イーサチャネルの状態を確認
4.pingを相互でvlan1に飛ばしイーサチャネルの疎通を確認
5.copyコマンドを使用し、スタートアップコンフィグに設定を反映

経路の冗長化、帯域拡張、トランクポートの設定は以上で問題ないと思われます。

 

設定の解説

では、順に解説していきます!(4,5は割愛)

1.スイッチA、スイッチBのFa0/2をケーブルで接続

これによってスイッチA―B間は二本のケーブルで繋がれた状態になっています。
しかし、ブロードキャストストームを防ぐため、STPによって一つのポートがブロッキングポートとなるので (RSTPの場合はオルタネートポートと名称が変わります)
二本繋いだけど、ループになっちゃうから一本だけ日頃使わないようにしといた という状態になります。

「なんだよ、それじゃ意味ないじゃん!!」

・・・と、待った待った。実はそんなことないんですね!
STPはループを回避するにプラスして冗長化もしてくれています。

そもそも 冗長化 とは…

まず例としてスイッチとパソコンの間にケーブルが一本あり、それを介してネットサーフィンをしているとします。
もしも、このケーブルが断線してしまったらどうなるでしょう・・・
当たり前ですが、パソコンはインターネットに接続できなくなりネットサーフィンも出来なくなってしまいます!ohᔪ( ᐪᐤᐪ )ᔭNo!

スイッチのケーブルをもう一本増やしてみましょう。
そうすると、ネットサーフィン中に片方のケーブルが断線したとしても、もう片方のケーブルがアクティブ状態となり接続が保たれるようになります!
これが冗長化!片方動かなくなってももう片方が動く!それが冗長化!
つまり冗長化を使用すると、可用性が向上するわけです!
STP以外にもRSTP、ルーターではVRRP、HSRP等、冗長化するためのプロトコルは色々あります。
設定によってはロードバランシング(負荷分散)も実現できる為、ネットワークを常時止めないという点においてとても重視される項目になります。

 

つまりは、日頃一本ケーブルを使わないだけで、片方が断線なりした場合はもう片方が肩代わりするわけです。便利ですね!
ということで、とりあえずの冗長化はケーブルの接続だけでOKです。

 

2.ターミナルでFa0/1とFa0/2にswitch mode trunkchannel-group 1 mode onを両方のスイッチに入力し適用

前者のコマンドを使用することにより、任意のポートをトランクポートに設定することが可能になります。
これによって複数のVLANの通信をトランクポートを通じ橋渡しができます!

後者のコマンドはイーサチャネルというものの設定をしています。
これは「複数の物理ポート」「一つの論理ポート」に束ねる技術です!
束ねたインタフェースをポートチャネルといい、ポートチャネルで接続する事で通信帯域を増やす事ができます!
STPでは片方のケーブルは日頃使わない状態になっていましたが、この設定を施すとケーブル二本の通信帯域を有効的に使用できるというわけです!
因みに、mode onの部分はネゴシエーションしない場合の設定となっておりますが、両方のポートでmode onの設定を入れておく必要があります。

 

この問題の設定自体は以上で終了です。

ですが、実際に反映されているか、自分の思ったように行われているかの確認のために以下を行っています。

3.show etherchannel summayを使用し、イーサチャネルの状態を確認

このコマンドを使用するとポートチャネルとそれに属しているインタフェースが見れるようになっています。

 

 

(´-`).。oO(showコマンド、ほんと便利だ)

 

まとめ

この問題では、「ネットワークが遅くなったりと不安定である」というのがトラブルの症状となっていました。

問題文の中に「冗長化と通信帯域の拡張」と対処すべき項目が記述してあったので、チームによってはスムーズに終わったのではないでしょうか。

また、今回とりあげられている冗長化はネットワークやサービスを止めないために重要であると思います。

必要となる場面は多岐にわたるので、解けなかった!知らなかった!という方は勉強してみてもいいかもですね!

ICTSC, イベント, コラム, 運用管理

こんにちは、whywaitaです。
「DMM.com Labo ツチノコ杯」第4回ICTトラブルシューティングコンテスト にて運営委員を務めさせて頂きました。

「DMM.com Labo ツチノコ杯」第4回ICTトラブルシューティングコンテスト(以下、トラコン)では全部で13問の問題が出題され、その全てが学生の手によって作問されました!
今回はトラコン初の試みとして、問題文の公開、及び、作問者自身による問題解説を行いたいと思います!

問題文(出題したそのまま)を公開します!

Redmineの意図しない挙動の調査について (Survey of behavior not intended for Redmine)

問題文(Problem statement)

最近入社した社員が、Redmineでエラーを起こしたらしい。
A junior engineer caused the error on Redmine.

「若手で1番優秀な僕がエラーを出すことはありえないですよ!バグなんて絶対作りません!」
“There is no possible way that there is something wrong with my configuration. I absolutley do not create bugs!”

Redmineに発生した挙動を判断し、新入社員が再び操作しても壊れないようにしてください。
Determine the error occurred on Redmine.

症状(Symptom)

  • 新人社員がRedmineを操作した所、意図していない挙動が発生している。(After the junior engineer changed the configuration for Redmine/Server, it started to malfunction.)
  • 新人社員が操作した後は誰も操作を行っていない。(No one has touched the server after the junior engineer.)

チェックポイント(Checkpoint)

新入社員が再び同じ操作しても壊れないようにしてください。
Even if the junior employee carries out the same steps he has done before, Redmine should not show any error.

問題解説

この問題を解くのに必要なのが、「ログを読む力」と「ミドルウェアへの理解」でした。
トラコンは初期からネットワーク系の問題が非常に多い傾向にあり、多くのミドルウェアに対する問題が問われる事が少なかったため、本問題ではそれに反してRuby on Railsで開発されているRedmineをベースとした問題を取り扱いました。

解法

最初に運営側が想定していた解法についてお伝えしたいと思います。
※一部ログなどが出ますが、記事作成用に問題を再現した環境を作成しており、問題環境そのままでないことをご了承ください。

ログのバックアップを取る

これは通常のオペレーションではあまり取り扱われないことではないかと思うのですが、今回はどのタイミングで新入社員が不正な挙動を行ったかのヒントが少ないです。
通常であれば時間ベースで追いかける事も出来ると想うのですが、コンテストである性質上問題文中に「新人社員が操作した後は誰も操作を行っていない。」という文面を盛り込みました。この文面から、各種ミドルウェアのログのバックアップ(障害が起きているであろう箇所)を取ると問題が解きやすかったかもしれません。

エラーログを探す

ここで「ログを読む力」が生きてきます。
ApacheやNginxなどのwebサーバのアクセスログが、1アクセス=1行に対して、Redmine(というよりRails)はそれ以上のログを生み出します。
このような時に、「どのようなログであるか」「どのように抽出すれば上手くエラー箇所だけを抜き出すことができるのか」を即座に判断する必要があるのです。
ここで、「すぐにお手製のワンライナーを書けるのか?」という疑問が出てきます。これは、普段からシェルで色々な文章を扱っている人で無ければ難しいかもしれません。

ということで、抽出したログが以下になります。
自分の場合はHTTPステータスコードでエラーが吐いている事から、grepコマンドの検索を使って検索しました。

原因を見つける

このログを見つければ原因自体は分かりそうです。
Redmineが利用しているデータベース(今回はMySQLでした)に問題がありそうですね。
ついでに”U+1F60A”という見慣れない単語が見えます。これは何なのでしょう?

検索してみると分かりますが、これは「絵文字」です。皆さんもslackやHipChatなどで利用しているかもしれませんね。
通常のUTF-8で設定されているMySQLデータベースに絵文字を入れようとして、エラーを出力しているようです。
ここを解決出来れば、何とかなりそうですね!

対処する

原因が判明したのであれば、それを解決するだけですね。
MySQLの設定ファイルはmy.cnfです。今回の環境であれば/etc/mysql/my.cnfにあるので、ここを編集します。
[mysqld]セクションに以下の文字列を追加すると良いでしょう。

設定ファイルを書き換えたら、MySQLの再起動を行います。これでMySQLがutf8mb4に変更されました!

対処する(その2)

回答を見ていると、上記の対応をして回答としているチームが散見しました。
原因を発見出来ていて素晴らしいのですが、ここで問題文のチェックポイントを見返してみましょう。
「新入社員が再び同じ操作しても壊れないようにしてください。」とありますね。
実はこのままでは「再び同じ操作をした時」同じエラーが出ないとも限りません。それは何故か?既存のデータベースがUTF-8のままだからです

ここが残念ながら出来てなかったチームが多かったです。(勿論この処理を行ったチームをいらっしゃいました!)
既存のデータベースをしっかり変換して、ようやく完答となります。お疲れ様でした。

まとめ

通称「Redmine絵文字問題」、如何だったでしょうか?
Redmineが利用している言語であるRubyはマルチバイト文字にデフォルトで対応しているのですが、MySQLを初めとするバックエンド類はまだまだデフォルト対応とは言えない物が多いように思えます。
最近は海外でも”emoji”の愛称で呼ばれるようになった日本発祥の文化「絵文字」を取り扱う事も多くなるので、動向・扱い方はしっかり捉えていきましょう!

余談

「Redmine 絵文字」で検索すると、かなり上の方にこのブログ記事が出てきます。

Redmine構築後のDBの文字コードをutf8mb4に変換して絵文字に対応する – Dig that groovy!

このブログを読むと完答までの流れが書いてあるのですが、実はこのブログの筆者はトラコンの運営委員だったのです!
参加者の方の中にはこのブログを読んだのかな?と思われる回答もありましたが、本人は複雑な表情をしていました(笑)

お知らせ, コラム

技術者のみなさん、いつの日か自分の得意分野について最高の技術書を書いてみたくありませんか? それも、どうせだったら出版社から発行して、モデルチェンジのたびにMacBook Proを買い替えられるくらい印税を稼ぎたいですよね。出版社というものは「売れる」技術書の企画を常に探しています。したがって、ほとんどの技術者の眼前には、ネタとやる気さえあれば技術書を上梓するチャンスが転がっているといっても過言ではありません。

しかし、いうまでもありませんが、チャンスがあることと実現することの間には「壁」が何枚も立ちはだかっています。「一冊分くらいの技術ネタは十分にあるし、執筆する時間もとれそうだ。小説とかわりと読むほうだし、文章力にはそこそこ自信がある。実は技術系の同人誌を出した経験もあるんだよね。」という、編集者目線でハイスペックなポテンシャルを秘めた技術者でも、いざ書き始めようとすると、そもそも書き出しが思いつかなくて気力が消滅したり、これ誰が読むんだろうって白けた気持ちになって進捗がアレしたり、うまい例題が思い浮かばなくて行き詰まるのがふつうです。枯渇しかけたモチベーションをレッドブルでひねり出しながらなんとか書き終えても、さっぱり売れなかったり、アマゾンで誰かに酷評されたりすれば、あとに残るのは悲しみだけです。印刷製本しちゃった場合には在庫も残りますね。

この記事を書いている人間は、IT系技術書を企画し制作する編集者として、数々の技術書の一生を見守ってきました(ここに職務経歴書があります)。その経験をもとに、「技術者が技術書で読者に評価されるためのコツ」みたいなものを紹介できればと思います。技術者にして出版人でもある高橋征義氏は、「技術書がなければ技術者は死んでしまう」と言っています。優れた技術書を書けるのは、優れた技術者だけです。この記事では、優れた技術者の方々に、「技術書を執筆したい、それも今すぐにだ」と奮起してもらえることを目指します。

技術書の評価がみるみる向上する5つの工夫

ソフトウェアにしろハードウェアにしろ、技術者が技術について解説する「ドキュメント」としては、いわゆるマニュアルや論文があります。ブログやメルマガなどで技術解説を書いたことがある人も多いでしょう。そのようなドキュメントと技術書とが決定的に違うのは、技術書は「商品」であるという点です。有料の技術ブログやメルマガもあるし、別売りのマニュアルなんかもありますが、流通する商品であることは技術書が他のドキュメントと一線を画する最たる特徴だといえます。(雑誌の記事なら書いたことがあるという技術者の方も少なくないと思いますが、商品としてのボリュームや責任の重さを考えると、雑誌の延長として技術書を考えるのは難しいかもしれません。)

お金を出して買ってもらう商品である以上、技術書を書くときに「商品として意識すべきこと」がいくつかあります。書き手がちょっとだけ意識することで読み手がハッピーになる、そんな工夫はたくさん考えられると思いますが、独断で大きく以下の5つに要約してみました。

  1. わかりやすく伝えるための工夫
  2. うそをつかないための工夫
  3. 読み終えてもらうための工夫
  4. 読み返してもらうときのための工夫
  5. 読み始めてもらうための工夫

この5つは、およそ「人に読ませる技術文書」のすべてについて必要な工夫ともいえますが、とくに技術書の場合には「お金をもらうレベル」で必要になります。まあ、商業出版をしようというケースであれば、これらの工夫は担当の編集者に任せればいいはずなんですが、書き手がこういうことを意識しているかどうかで出来上がりはずいぶん違うものです(それに、経験によると、こういう工夫ができる編集者とできない編集者がいます。備えよう)。

なお大前提として、「何を誰に向けて書くか」はすでに決まっているものとします。つまり、ネタの選び方はこの記事では触れません。対象読者を決めることの重要性についても触れません。すでに伝えたいトピックが見つかっていて、どんな技術レベルの読者向けに解説を書きたいか、おおざっぱに決めている人がこの記事の対象です。対象読者を見据える重要性や題材の選び方について手っ取り早く知りたい人には、次の本が参考になるでしょう。

山内俊介 著 『専門家のための「本を書こう」入門』

https://www.amazon.co.jp/dp/4904536665

1. わかりやすく伝えるための工夫

のっけから失望させてしまいそうですが、技術的なトピックをわかりやすく説明する安直な方法はありません。でも、技術書をわかりにくくするのなら簡単です。そんなアンチパターンとして頻出なのは次の3つ。

  • 用語の解説ばっかり
  • 図や表だけで説明が終了
  • 具体例や動機を示さない

ときどき、技術用語の説明文を並べることで技術書を執筆していく人がいます。用語集ならそれで構いませんが、そうでないなら、その用語が必要になる背景をなんとかして説明してください。背景になる概念がうまく伝われば、それに名前を付けることで、自然な流れで技術用語を説明できます。たとえばC言語の入門書を書いていてポインタについて説明したかったら、「ポインタとは……です。」という用語解説スタイルで理解してもらうのはたぶん絶望的に困難であり、そもそもポインタが必要になるような状況のほうを解説してあげるほうが本質をよく理解してもらえそうですよね。どんな技術書でも状況は同じです。「およそあらゆる概念は用語の説明をするだけでは伝わらない」という態度を原則にして執筆しましょう。

図や表を描いて説明終了というのも、技術書における典型的なアンチパターンです。よく見かけるのは、フローチャートのみで説明に代えているケースです。どんな図表にも、すでにわかってる人にしかわからない見どころがあるものです。「図を見ればわかるでしょ」という態度で執筆されていると、たいていの読者は面食らってしまいます。うまい図や表は読者の理解を促進させますが、その図だけで理解できる話なら、そもそも技術書という形の込み入った解説は必要ないでしょう。図や表で解説をしたつもりになってはいけません。図表は本文の解説を補うために使ってください。

最後のアンチパターンは、具体例や動機付けに欠ける説明です。その技術が「どうやって」問題を解決するのかだけでなく、「どんな場面で」「なぜ」その技術が必要になるのかを伝えましょう。そもそも、ある技術によって解決する問題が見えているのは、その技術を十分に理解している人だけです。これからその技術を勉強しようという人に向けて、その技術が世界のどんな問題を改善するのか、なるべく具体的に明示してあげてください。いかにうまい例をひねり出すかが勝負です。

なお、ここで必要だと言っているのは「具体例」であり、「たとえ話」のような「例」ではありません。よく言われることですが、技術書では比喩の扱いに注意してください。使っちゃダメっていうことはありませんが、それがあくまでも比喩であることを明らかにしましょう。その比喩を解説の根拠にするのはもってのほかです。

わかりやすい説明を書くためには、文章力が必須なのでは?

そんなことありません。

とはいえ、文章力がまったくなければ何も書けないため、それなりに日本語をがっつりと書く覚悟は必要です。でも、技術書に必要なのは「ぐっとくる情緒的な文章」ではないので、たとえば面白い小説とかブログ記事を書くのに必要という意味での文章力は、あるに越したことはない程度だと考えてください。技術書にとって本当に必要な「文章力」は、うっかり間違った説明を書いてしまったり、意味が特定できない文章を書いてしまったり、そういう問題を避けるためのものです。そのような意味での「文章力」については「2. うそをつかないための工夫」で説明します。参考書籍としては、やや学術的ですが、次の本の第2章と第3章を挙げておきます。

森口 稔 著 『テクニカルコミュニケーションへの招待』

https://www.amazon.co.jp/dp/4385366020

ただし技術書の文章は、論文の文章のように無駄を一切そぎ落とす必要があるわけではないので、ところどころで「ぐっとくる文章」を狙ってみるのも悪くないと思います。その辺はいろいろ工夫してみてください。可能なら担当編集者やレビュアーにも相談してみましょう。

「わかりやすく伝えるための工夫」のまとめ

  • わかりにくい解説のアンチパターンを避ける
  • いわゆる「上手な文章」を書く自信がなくても大丈夫

2. うそをつかないための工夫

なにより重要なのは真摯な態度です。わからないことはわからないと書きましょう。全知全能でなければ技術書を書いていけないわけではありません。あるいは、知らないことは書かないようにしましょう。個人的な意見ですが、浅く広い情報を紹介するよりも、フォーカスをぐっと絞ったほうが良い本になる場合が多いです。

意外と陥りがちな罠は、「難しいことを易しく説明してしまう」です。これは絶対やっちゃだめ。難しいものは難しいのです。理解するには時間がかかるものなのです。だから安易な説明で「わかった気にさせる」のではなく、じっくり説明したり、説明の仕方を工夫したりすべきです。まあ、それが難しいんですけどね。

説明文を書くときは文法にも気を付けましょう。といっても、学校で習うような文法に忠実であれという意味ではありません。どんな言語にも、ネイティブだと無意識に見過ごしてしまう暗黙の性質があるものです。たとえば、なにげなく使った助詞の「の」に誤読を招く可能性があるとか、そういうのを執筆時に意識しましょうという話です。意識できるようになるには、やっぱり文法に立ち返るしかありません。日本語の文法については、たとえばこんな本を一冊読んでおくだけで、ずいぶん見方が変わると思います。

益岡 隆志 著 『24週日本語文法ツアー』

https://www.amazon.co.jp/dp/4874240844

知らないと意識できない部類の落とし穴として文法より致命的なのは「誤謬」です。操作手順のような文章だけを書いているぶんには心配いりませんが、技術の必要性を説く文章や、概念をかみ砕いて説明する文章では、うっかり論理展開がおかしくなってしまうことがあります。幸い、おかしな論理展開はある程度パターン化されているので、そのような「誤謬」を避けたり、校正時に気づいて修正したりするためにも、一通りさらっておくのがよいでしょう。

Wikipedia: 誤謬

https://ja.wikipedia.org/wiki/%E8%AA%A4%E8%AC%AC

Wikipedia: 詭弁(こちらも参考に)

https://ja.wikipedia.org/wiki/%E8%A9%AD%E5%BC%81

「うそをつかないための工夫」のまとめ

  • 知らないことは書かなくてもよい
  • 難しいことを易しく説明しない
  • 文法に敏感になろう
  • へんな論理展開にも敏感になろう

3. 読み終えてもらうための工夫

大前提として、あなたの本を読み始めた人がみんな必ず本を読み終えてくれるわけではない、という覚悟をしてください。このブログだって、ここまで到達していない読者が大半でしょう。そのうえ技術書ときたら、ブログに比べると圧倒的に長い。読み始めたけど時間がなくて読めなくなる人、その技術の解説が不要になった人、自分に合わない本だと気づいた人、当然いろいろな読者がいます。なんだかんだ言って、全部を読まなくても内容が理解できる技術書がベストなんです。

それでも書いている側としては、なるべく「全員の読者がハッピーに読み終えられること」を目指さなければなりません。そのために必要な工夫は、ずばり「段落」です。

技術書の目次構成をものすごーく粗くとらえると、「部」や「章」を適切に並べたものだといえます。部や章が適切な順番に並んでない本は、とても読みずらいので、読み切ってもらえる見込みはほとんどなさそうです。

目次構成をさらに下に降りていくと、「章」の中には「節」があります。節の構成がぐだぐだな章が読みにくいのは必然ですね。さらに「節」の中には「項」があり、項の順番がうまくないと節が読みにくくなります。最後の「項」を構成するのは、目次には見出しとして現れませんが、「段落」です。技術書の構成の最小単位は、実は目次には現れない「段落」だということです。

構成の最小単位は段落

いま見た技術書の構成をボトムアップで見ていくと、段落が適切に並んでいないと項が読みにくくなり、さらに節が読みにくくなり、章や部が読みにくくなり、書籍全体として読みにくくなるといえます。読みにくい本より読みやすい本のほうが最後まで読んでもらえるはずなので、段落がうまい具合に並んでいる技術書のほうが最後まで読んでもらえそうですよね。

ただし、これは、そもそも各段落がきちんと「技術書の構成の最小単位」になっていることが前提です。一つの段落にたくさんの内容を詰め込んだり、逆に意味をなさない段落を大量に作ったりすれば、どうがんばって並べても読みにくい技術書にしかなりません。

ある程度まとまった文章を書いたら、段落ごとに「何を伝えている段落なのか」を要約してみましょう。そして、その段落たちの適切な並びを何度も何度も検討してみましょう。足りない段落がないか、重複する機能を持った段落がないか、自己レビューしてみましょう。文章における段落は、プログラムやハードウェアにおける「モジュール」のように考えるとよいかもしれません。モノリシックなモジュールは悪です。不要なモジュールも悪です。モジュール間の連携がとれていないと、製品はまともに機能しません。

段落をうまく制御することは、技術書に限らず、あらゆる技術文書にとって「鉄則」です。これについては、とりあえず次の本を絶対に読んでおきましょう。

木下 是雄 著 『理科系の作文技術』

https://www.amazon.co.jp/dp/4121006240

段落を並べて、文脈を作る

段落の並べ方に鉄壁のルールはありません。大まかな道筋としては、概要からスタートして細部の説明に入っていくのがいいでしょう。でも、何が「概要」で何が「詳細」かは文脈、つまり自分がいま何をどう説明しているのかによります。段落を整理するときの心がまえは「文脈をうまく作り出せるように並べる」です。「この段落は、自分の本をここまで読んできた読者にとってどんな役割があるか」をよく考えてください。読者にとってつらいのは、文脈における各段落の役割を見失ってしまうことです。すべてが腑に落ちるまで、何度も段落の切り分けや配置を工夫してみてください。

ちょっと脱線しますが、技術書を書くという行為は、小説のような読み物を書くのとは違って、一本の糸をつむぐことではありません。自分がみんなに伝えたい技術について、「線」ではなく「面」で解説することを心がけると、良い技術書になることが多いように思います。縦糸をたらしたら、必ず横糸を張る。文豪クラスの筆力を持っていて、一本の糸を編み物のように編み込んで面を作り出せる著者もたまにいますが、たいていの人には無理です。それができることを目指す必要もありません。あるトピックを解説するときに、それが全体の中でどういう位置づけにあって、なぜここで解説が必要なのかを、しつこく読者に思い出させてあげればいいのです。

「読み終えてもらうための工夫」のまとめ

  • 技術書の最小単位は、段落
  • モノリシックな段落や不要な段落を撲滅する
  • 段落を並べて文脈をうまく作り、読者を迷子にせずに面で解説する

4. 読み返してもらうときのための工夫

技術書は小説などの文芸書と違って、いったん読み終えてからも必要な情報を参照するためにランダムに見返されることが多い本です。意外かもしれませんが、紙の本というメディアは案外とランダムアクセス性に優れています。つまり、読みたい場所へとアクセスしやすいメディアです(しょせんはアナログメディアなので検索とかは不得手ですが、ことランダムアクセス性に関しては、まだ紙の本のほうが優れているかもしれません)。

そんな紙の本のランダムアクセス性を生み出しているのは、パラパラとページをめくって参照したいページを目で捕まえるという単純な動作です。この動作を助ける工夫をしてあげることで、使い勝手がよい技術書になれます。実際、世の技術書編集者もさまざまな方法で「読み返し」を助ける工夫をしています。

プロ編集者が得意なのは、レイアウトを工夫したりイラストを挿入したりすることで、本のあちこちに「目が引っかかる」場所を作ることです。学校のテスト中に、「この用語が思い出せない……教科書のあの辺に書いてあったのは覚えてるんだけど」という苦々しい気持ちになったことはありませんか? 人間、そんなふうに「書籍のページの雰囲気」はよく覚えているものです。紙面のレイアウトに変化をつけたり、ところどころにイラストを挿入したりするのは、組版屋さんがなんとなくでやっているわけでもないのです。レイアウトやイラストは著者が自分で工夫するのは難しい部分ですが、図とか表とか、あるいは数式とかコラムとかで、著者自身がそういう「ページにおける目の引っかかりどころ」を工夫をできる場合があります。

読み返してもらうときの工夫として、目次や索引も忘れてはいけません。技術書では目次や索引を付けるのは「あたりまえ」です。とくに索引は、全文検索の下位互換と思われがちですが、技術書に対して別の見方を提供できる便利なコンテンツです。この話は長くなるので、気になる方は手前味噌ですが以下のスライドに目を通してみてください。

Keiichiro Shikano “Indexing makes your book perfect”

https://www.slideshare.net/k16shikano/imybp-light

「読み返してもらうときのための工夫」のまとめ

  • とくに紙の本は、わりとランダムアクセス向き
  • それならば、ランダムアクセスする場合のことを考えよう
  • 目次とか索引を上手に使おう

5. 読み始めてもらうための工夫

技術書は、その技術を必要とする人が読むものです。ということは、ある技術書を読み始めてもらえるかどうかは、その本で解説している技術そのものの需要によってほぼ決まりそうですね。誰もが注目している新技術で、とにかく解説本が求められているという状況なら、「○○についての日本で最初の解説書」というだけで読み始めてもらえるでしょう。

でも、そういう本を書けるチャンスは必然的に限られます。うまくチャンスを見つけて書き始めたとしても、そもそも「最初の解説書」になれるとは限りません。怒涛の執筆力で「最初の解説書」の座を獲得できたとしても、次々に競合書が出てきてシェアを奪われるのは時間の問題でしょう。みんな考えることは同じなのです。

というわけで多くの技術書は、「みんながまだ必要性に気づいていない新技術」とか、「ある技術をよりよく理解するための基礎知識」とか、「特定の部分にフォーカスを絞ったすごく深い解説」とか、逆に「広い知見を得るための概説書」とかになるでしょう。こういう本は、何も考えずに執筆するだけでは読んでもらえません。というか、まず買ってもらえません。「この本の内容はこんなに価値があるから、みんなこの本を買って読むべきです!」というメッセージを作っている側が打ち出す必要があります。

読み始めてもらうために使えるツールとしては、「書名」や「カバーデザイン」のほか、「はじめに」とか「有名人による推薦文」、「帯」(カバーの上から巻いてある宣伝文とか載っているやつ)などがあります。出版社から発行する技術書の場合、「はじめに」はともかく、ほかの要素は著者の一存で決められない場合がほとんどですが、とくに「書名」については、企画の段階であれば著者として大いに提案できます。その際には、自分がかっこいいと思う案を提案するのではなく、「この本を必要としている人に手に取らせて読ませるための動機を与えるのに適切なタイトルは?」という具合に考えましょう。

さらに重要なのは、いわゆる「パブリシティー」です。出版社に任せるだけでは、潜在的に読んでほしい技術者には届きません。FacebookやTwitterでの徹底的な告知、非公式サポートページの準備、書評を書いてくれそうな人への献本、教科書にしてくれそうな教育機関への売り込みなど、すべて自分でやってしまうくらいの気持ちで十分です。このようなパブリシティーについて出版社の影響力は案外と限られています。自分でやるほうが、間違いなく良い結果になります。

「読み始めてもらうための工夫」のまとめ

  • ほとんどの本は、読んでもらうまでは存在しないも同然である
  • 読んでもらうための努力が必要
  • とくにネットでのパブリシティーは出版社に頼るな

「良い本だったけど赤字に終わったね」を技術書界から駆逐したい

というわけで長々と「売れる技術書の書き方」みたいな話を書いてみました。念のため免責を述べておきますが、ここに書いてあることを実践したからといってあなたの技術書が売れるという保証はありません。でも内容は間違いなく向上します。読んでもらう機会もきっと増えるでしょう。

技術書編集者が原稿に対峙するときに気を付けていることは、ここで上げた5つの工夫のほかにも、まだまだたくさんあります。句読点との付き合い方や文のリズム、箇条書きの使いこなし、対象読者とのインピーダンスミスマッチの整合、参考文献の形式などなど、それぞれの編集者の頭の中には言語化しにくい独自のノウハウや要出典のセオリーが山ほど抱え込まれているはずです。この記事をきっかけに、そういう工夫が見える化されて共有されたり、著者が自分で勝手に取り込んでいって原稿の質がもりもり改善されるといいなと思いました。

最後に、この記事はツチノコブログという技術書とはあまり関係なさそな媒体に掲載してもらえることになりました。ツチノコブログの中のみなさんの寛大な心に本当に感謝します。ありがとうございます。

PAGE TOP