SHOEISHA iD

※旧SEメンバーシップ会員の方は、同じ登録情報(メールアドレス&パスワード)でログインいただけます

CodeZine編集部では、現場で活躍するデベロッパーをスターにするためのカンファレンス「Developers Summit」や、エンジニアの生きざまをブーストするためのイベント「Developers Boost」など、さまざまなカンファレンスを企画・運営しています。

先輩ライターに訊く、技術文書執筆のアレコレ

先輩ライターに訊く、技術文書執筆のアレコレ(1)
~花井志生(宇野るいも)さん

技術文書執筆の現場(1)

  • X ポスト
  • このエントリーをはてなブックマークに追加

3 技術解説文書の種類

 これまで自分が書いてきた代表的な技術解説文書には2通りあるようです。1つは紹介系の文書、もう一つはknow-how系の文書です。紹介系の文書は、まだ日本では一般に知られていない新しい技術を解説するものです。多くのケースでは英語の資料しかなかったり、あるいは資料そのものが不十分だったりほとんど存在しなくて、ソースコードを読むしか動作を確認する方法がなかったりします。一方know-how系の文書は、私が日頃体験した事柄の中から、他でも役に立つと思われるもの(あるいは単に技術的に面白いと思われるもの)を体系化してまとめたものです。

3.1 テーマの選択

 執筆するテーマを選択する際には何に気をつければ良いのでしょうか。ここでは私が普段から感じていることを順不同で挙げてみたいと思います。

3.2 BCGマトリクス

 BCG(Boston Consulting Group)マトリクスは、製品のポートフォリオを比較検討して戦略を立案するために用いるもので、市場の成長率、市場の占有率を2軸にとって自社、他者製品を配置してみて、自社製品の強み、弱みを客観的に分析します。今回は、市場の成長率をテーマの先進性、市場の占有率を読者の多さと見たてて、執筆テーマのポートフォリオを検討してみましょう。

BCGマトリックス
BCGマトリックス

 先進性が高く読者層が多い場合、図の星が書かれている部分にプロットされます。新しく出てきた技術が非常に多くの技術者の注目を集め、そこにタイミング良く執筆を間に合わせることができたようなケースです。この場所を狙うことは非常に困難で、どちらかと言えば偶然の産物と言えるでしょう。なぜかというと特に先進性の高い技術の内容を執筆するには時間がかかりますから、タイミング良く出版するためには、まだ市場では下火のころから執筆を開始しなければなりません。これは出版社にとっても執筆者にとってもリスクの高いかけなので、なかなか実行には移せないのです。

 先進性が低く読者層が少ない場合、図の犬の部分に相当し、これは「負け犬」と呼ばれます。こうしてマトリックス上にプロットしてみて冷静に考えれば、間違ったテーマを選択する可能性を下げることができるでしょう。

 先進性が高く読者層が少ない場合、図のはてなマークに相当し、ここは「問題児、ワイルドキャット」と呼ばれます。エンジニアが趣味で選んでしまったテーマは、ここにプロットされることが多いかもしれません。そのまま市場が拡がらずに終わってしまったり、内容があっという間に陳腐化してしまう恐れもありますが、市場が小さいので競争もほとんどなく、一定の部数は見込めるはずですし、うまくいけばそのまま読者が増えていくかもしれないという期待も持てます。

 先進性が低く読者層が多い場合、図の牛のマークに相当し「金のなる木」と呼ばれます。ここはいわゆる初心者向けの解説本で、技術力よりも、いかに分かりやすいかとか、おもしろくて飽きずに読み続けられるかとか、イラストの萌え要素とかの勝負となります。競争も激しくパイの奪い合いとなり、当たれば大きいですが、その裏には敗者の屍が累々と続くことになります。

 さて私の個人的な意見ですが、テーマとしては、図のはてなマーク周辺を狙うのが良いと思います。星は狙って掴めるものではありませんし、牛で勝負するには技術力とは別の能力が要求されるからです。

3.3 合わせ技

 テーマの選択について前節で触れました。ここではもう一つの考慮点としてテーマの組み合わせについて触れたいと思います。まず1点勝負を避けましょう。あなた自身がその筋の専門家なら良いですが、そうでないなら、そういった専門家にはその分野で勝つことは難しいです(それでも書きたい場合は、共同執筆者や、レビュアーに取り込んでしまいましょう)。しかし合わせ技のテーマであれば、勝ち残ることが可能かもしれません。例えば「Javaのシステム開発」で「エンタープライズ・アプリケーション開発」で「数百人規模の開発」の場合の開発運用方法のknow-howや失敗談となれば、自ずと書ける人は限られてくるでしょう。

3.4 紹介系文書を執筆する

 紹介系の文書を書く場合には、その分野での最先端技術の追っ掛けをしておく必要があります。とはいっても「本当の最先端」でなくて構いません。「そろそろ日本でもはやりそう」くらいの先端技術で良いのです。BCGマトリクスで見た通り、あまり最先端だと「早すぎ」て失敗します。とはいえこの「そろそろはやりそう」というものを嗅ぎ分けるのは、なかな難しいものです。このため、ある程度幅広く情報を集めておく必要があります。

 情報を集めたら自分でも試してみます。ソースコードやフォーラム、メーリングリストを覗き、どの程度活発に開発が進んでいるかを調べます。ドキュメントが整備されていることは望ましいですが、必須ではありません。むしろドキュメントが不足していた方が、解説文書の価値は上がるでしょう。

 技術調査で注意点が1つあります。エンジニアというのは技術に惚れやすいもので、好きな技術を盲目的に高く評価してしまいがちです。そうでなくてもどうやらエンジニアというのは、勉強したてての技術をその本来の価値以上に高く評価してしまう傾向があるようです(思い当たるところがありませんか?)。自分の場合は特に若い時にその傾向が顕著で、CPUやOSの選択でひたすらマイナー路線を突っ走っていたように思います(CPUは、6800 -> 6809 -> 68000、OSは、OS9 -> OS9-68000)。しかし文書を執筆してそれを売り出すからには、なるべく多くの読者がついてくれることが必要なので、ある程度離れた目でその技術を客観的に判断する必要があります。なるべく目線の異なる他の人の意見、特に年上の人の意見を聞いてみてください。IT業界の技術というのはどんどん新しいものが出ているようで、実は概念的には同じような考えの揺り戻しが何度も起きています。例えば集中と分散という流れは集中へ向かったり分散へ向かったりと振り子のように揺れています。この業界での経験の長い人なら、こうした流れを見てきているので、一見まったくの新しい技術でも、その問題点を簡単に見抜いたりするものです。

 先進性が高いソフトウェアをテーマに選んだ場合、執筆中に何度もバージョンアップして書き直しを迫られる可能性があります。Web上の資料もどんどん陳腐化して間違った情報と化していきます。最後に最新バージョンに合わせるための作業期間を見込んでおきましょう。

3.5 know-how系文書を執筆する

 次にknow-how系の文書を書く場合ですが、これは日頃の仕事での気づきをメモしておくことから始めます。何か仕事で工夫したことがあれば、それが他に展開できないか、汎用化できないかといったことを考えてみます。また何か失敗した、あるいは苦労したことがあれば、その本質的な原因が何なのかを掘り下げて考えてみます。例えば表面的には採用したツールの生産性が悪かったという事象だとしても、なぜ生産性が上がらなかったのか、ツール本来的なものなのか、ツールが今回のプロジェクトに合わなかったのか、メンバのスキルが合わなかったのか、原因はいろいろ考えられます。もしもツールが合わなかったのだとしたら、なぜそのようなツールを選んでしまったのか、それを解決するには次回は何を工夫すれば良いと考えられるのか、掘り下げる点はいくらでも出てくるはずです。とかく実プロジェクトでは日頃の作業に忙殺されて、こういった掘り下げを行う機会がありません。まだ記憶が新鮮なうちにメモをとっておくのが良いでしょう。

 know-howを蓄積する際に注意点が1つあります。実際に現場で仕事している人間は、自分の工夫や気づきをとるにたらないものと過少評価してしまいがちです。どんなにつまらないと感じてもメモを残しておいて、後で見てみてください。後から見返すと、きっといろいろな気づきが得られるでしょう。こうしたメモはついつい紛失しがちなので普段から場所を決めておくのが良いでしょう。PC上のローカルファイルだと、PCの故障や買い替えで紛失しやすいので、Google DocsとかDropboxのようなクラウドサービスを使うのがお勧めです。

3.6 その道の専門家が良い解説文書を書けるわけではない

 世の中にはいくらでもその分野の専門家がいます。そんな中で自分が文書を書く価値などあるのでしょうか? きっとあります! まず上で述べた通り、1点勝負を避け合わせ技で勝負すれば、勝負できるところが見つかるはずです。そして、実はその道の専門家というのは、解説文書を書くのにはあまり向いていません。なぜなら、そういった人達の回りは専門家ばかりで、分からない人を対象に解説をする機会が乏しいのです。1を言えば10まで分かってしまえる人に囲まれて仕事していたら、分からない人の気持などそうそう想像できるものではありません。

次のページ
4 執筆作業の実際

この記事は参考になりましたか?

  • X ポスト
  • このエントリーをはてなブックマークに追加
先輩ライターに訊く、技術文書執筆のアレコレ連載記事一覧

もっと読む

この記事の著者

花井 志生(ペンネーム 宇野るいも)(ハナイ シセイ(ペンネーム ウノルイモ))

※プロフィールは、執筆時点、または直近の記事の寄稿時点での内容です

この記事は参考になりましたか?

この記事をシェア

  • X ポスト
  • このエントリーをはてなブックマークに追加
CodeZine(コードジン)
https://codezine.jp/article/detail/6165 2011/09/26 14:00

おすすめ

アクセスランキング

アクセスランキング

イベント

CodeZine編集部では、現場で活躍するデベロッパーをスターにするためのカンファレンス「Developers Summit」や、エンジニアの生きざまをブーストするためのイベント「Developers Boost」など、さまざまなカンファレンスを企画・運営しています。

新規会員登録無料のご案内

  • ・全ての過去記事が閲覧できます
  • ・会員限定メルマガを受信できます

メールバックナンバー

アクセスランキング

アクセスランキング