座談会
前編 こうやって技術文章書いてます

2回シリーズの第1回目は、そもそもエンジニアに文章力って必要?という話からスタート。CodeGridの原稿を例に、技術文章をどのように書いているか、具体的な手順とともに、赤裸々に語ります。

2016年09月23日発行

目次

はじめに

ピクセルグリッドのスタッフは、このCodeGridという媒体のための執筆をしています。そのため、比較的技術文章を書く機会が多いと思われます。また、書籍執筆経験があったり、外部メディアへの寄稿を行うスタッフも少なくありません。そこで、スタッフに集まってもらい、技術文章を書くノウハウを、自分の執筆作業を振り返りながら語ってもらおうと思い立ちました。

また、座談会に先立って、座談会に出席しなかったスタッフも含め、アンケートを行いましたので、その結果も合わせて紹介します。

座談会参加者は以下のとおりです。

業務で必要になる文章力

坂巻:今日のテーマは「技術文章」ですよね。エンジニアに文章力って必要だと思いますか? ずどさん(高津戸)って今、案件のドキュメントをまとめる業務をやってますよね。

高津戸:ああ、そうですね。仕様要件に基づいてデザインが上がるんですけど、そこには書ききれていない挙動や、UIで使われている用語、それから共通の仕様などを書くんですよ。普通に文章をたくさん書いてますね。

坂巻:なるほど。

高津戸:そういう仕事でなくても、プロジェクトを進行していると、たとえばメールでも、プロジェクト管理ツールを使ってでも、クライアントとやり取りしていると、お互いにいろいろ文章でコメントし合うじゃないですか。それやっているだけで普通に1日終わる(笑)。そういうときにやっぱり的確な文章を速く書けるようになったらいいなって思いますね。

坂巻:わかりやすく簡潔に、っていうの大事です。長いと読む気が失せますから。

中村:メールの文章はそうとう気を付けてますよ、僕は。わりと対応が難しめのメールを書くことが多いんです。こちらにはまだ事情がわからないんだけれども、とりあえず相手が怒っているとか。こういう状況で大切なことは、間違わずに相手に伝えることと、メールの長さですね。

高津戸:わかりやすさということだと、ありがちなのはエンジニアにしかわからない専門用語をお客さん向けの文章で使ってしまうこととか。相手はコードのことはよくわからないのに、そういう話を中心に書いてしまうとか。

中村:そうね。コードの構造を前提に、それを知ってないとわからないような内容を展開してしまうとかね。

高津戸:CodeGridの記事をやり取りしているときにもないですか(笑)?そういうこと。編集していて、「ここはprototypeだからどうのこうの、って私に言われてもね」って思うことないですか(笑)?

外村:あるかも(笑)。

中村:コミュニケーションの話ですよね、相手のコンテキスト、つまり持っていると思われる知識をベースにどういう回答をするかっていう。記事を執筆してても、相手のレベルはきちんと想定して、その相手にわかる言葉で書くようにしてます。

小原:案件と同じで原稿にも必ず「相手」がいるからねえ。

文章力は「相手」のことを考える力

中村:ブログを書くエンジニアも多いと思うけど、僕の場合、ブログは自分に向けたメモだから(笑)。

外村:そういう前提ですね。わからない人がいても「ごめんね」で済む。でも、案件の「お客さん」や記事の「読者」に対しては、それではいけない。特にお客さんの場合、相手の能力ってどうやって把握するのですか?

中村:打ち合わせのときなどに相手が使う言葉とか、あとは案件で上がってくる先方の要求かな。それを踏まえた上で、この人だったらこれが通じるだろうと判断してますね。

坂巻:ちょっとづつレベルを上げてみたり(笑)。最初は知識がないものだと思って話すんですけど、これがわかるんだったら、これも大丈夫かな?と。様子見ながら。

中村:探ってくかんじはあるよね。あと、うまく通じていないようなら逆に下げていく。

外村:メールだと相手の人数は少なめですし、内容や語彙を調整していくことができると思うんですけれど、CodeGridの原稿だと比較的大勢の人を対象としていますよね。記事を一度配信したら、調整が細かくできないという難しさもありますが。

中村:それを完全にやることは無理だと思って諦めてますね。自分の想定した人に向けて書くけれど、読んだ人がそのレベルに合うかどうかはわからないので。とはいえ、なんとなくCodeGrid読者はこれくらいかな? という感触はあります。CodeGridのパーティーをやったときに会った方々の話を聞いて、こういう人たちがいるのだなというのはわかっているので。それを元に書いています。

坂巻:僕はそとさん(編集の外村)ですよ(笑)。僕が書くものに関しては、そとさんがわかったらいいなと思って書いてます。つまり「ある程度CodeGridを読んでいて、ちょっと技術に触れている人」を対象にしたいので、そとさんくらいだといいかなあって思ってます。

外村:そうなんですね(笑)。それはちょうどいいかも。

【アンケート結果】業務で文章力は必要か?

この座談会に先立って、文章を書くことについて社内でアンケートをとりました。エンジニア、デザイナー11名から回答をもらいました。座談会の進行に合わせて、アンケート結果も紹介していきます。

【質問1】エンジニアとして仕事をしていて、「文章力」があったらいいな(あるいは文章力あってよかった)と思うことはありますか?

回答 人数
よくある 10
たまにある 1
あまりない 2
まったくない 0

【質問2】ある(よくある、たまにある)と答えた方に聞きます。それはどんな場面ですか?(主な回答)

仕事での場面

  • クライアント向けの技術的な資料を書くとき
  • メールでの説明、ドキュメントの解説
  • 先方の仕様書やメールにツッコミをいれるとき
  • なにかドキュメントを書くとき
  • パフォーマンスチューニングでフィードバックするとき

原稿など執筆での場面、ほか

  • CodeGridの原稿を書くとき
  • Webメディアへの寄稿時
  • ブログの執筆時
  • ツイート文を考えるときなど
  • 同僚、クライアントや協力会社とのやり取りにおいて、課題の共有や自分の考えを提示したいとき

クライアントとのやり取りは圧倒的に文章が主な手段なため、その場面において、文章力を必要と考える人が多いです。あとは、納品されるドキュメントも成果物の一部であるため、けっしておそろかにできないことがわかりました。

原稿はどういう手順で書いている?

外村:書き方の話に入ってきたので、CodeGridの原稿を書き上げる手順を聞きたいです。

ーー「書けます」と答えたときに8割が決まっている(杉浦)

坂巻:アンケート見ていくと、だいたい同じなんですよね。書き方の手順は。りぃさん(杉浦)の一番目の手順の「指令を受ける」がおもしろかった(笑)。りぃさんはたぶん脳内できちんとアウトラインをつくって書くタイプだと思うのですが、脳内で構想している時間は長いんですか?

杉浦:ネタによりますね。でも、だいたい「このネタでお願いしたい」って言われて、「あ、それなら書けます」って答えたときには、もう自分の中では、8割くらいは書くことが決まっているので、あとは忘れないうちに手を動かすだけです。書き上げるまでが早いのは、仕事を手元にためておくのが嫌いだからですね。

高津戸:ということはりぃさんにはネタを提供すれば、書いてもらえるのか(笑)。

全員:(笑)

ーーデモつくりから入ることも(高津戸)

坂巻:一方、ずどさんは、アウトラインをリストでつくっておいて、Markdownで書いていきながら考えると。

高津戸:ああ、だいたいそうですね。スライドとかをつくるときも一緒ですね。

外村:書いていくんですね? 見出しレベルだけ書くのではなくて、書けるところから書いてしまう?

高津戸:うーん、そのあたりはマチマチですね。見出し書いて、少しだけ書くこともありますし、見出しも内容も書いてしまうこともあります。あとは、たとえばCSSのプロパティを解説するみたいな記事だと、そもそも構成を考える前にデモをつくっていろいろ検証しますね。そしてその検証結果をさらに仕様と突き合わせて理由を調べることをやっていることも多いです。

坂巻:僕はこの機能を説明するためにはどういったデモがわかりやすいかってことを考えなくちゃいけないんで、デモは文章を書いたあとで考えますね。わかりやすいデモができたなと思ったら、それを元に解説を書いたりしています。

ーー頭の中で考えてから一気に書くことも(中村)

中村:僕はデモが入ってくる記事はあまり書くことはないのですが、技術系の記事を書くときは何かしら実務で使ったものを解説することが多いので、デモ作成に時間を使うことはまずないですね。記事を書くときに、もう一度検証はもちろんしますけれど。

外村:構成はどうやって考えてます?

中村:ちゃんとしたアウトラインはつくってなくて、箇条書きをわっとつくります。この箇条書きは、構成というよりは、自分のハマったポイントや、落としてはいけないこと、書きたいことを入れていきます。その順番を入れ替えたり、これは全体の流れから外れるよねというものを除外して全体がひとつのストーリーになるように考えていきます。

外村:経営をテーマにした記事もたくさん書いていますよね? テーマが違うと書き方も変わります?

中村:「ピクセルグリッドの仕事術」シリーズを書くときなどは、頭の中でどういうことを書くかずっと考えてます。そのままわっと書けることもあるし、書けないときは、やはりまず落としてはいけないことを先行して書いてしまいます。あとは全体がうまくつながるようにしながら、書き加えていって終わりというかんじですかね。

外村:全体をひとつのストーリーにしていく論理展開で苦しむことはあまりないんですか?

中村:論理展開はそんなに苦しまないですけど、僕がいちばん苦しんでいるのは脳内で構成しているときで、期間的にもいちばん長いです。ま、だいたい原稿を出すのが遅いので、編集の人はわかっていると思うんですけど(笑)。

外村:じゃあ、書くときにはもう流れはほぼ決まっている?

中村:もちろん書きながら変えるときはあるけれど、だいたい決まっていて、ほぼできている状態になってから書き始めます。そのほうが早いので。知り合いの元編集者で本の執筆をなさる方がいるんですよ。その方は原稿の執筆がものすごく早い。で、その方が言っていたことは、180ページくらいの本1冊の分を内容を頭で考えていて、執筆時は2日くらいホテルにこもって全部書いてしまうそうです。すごいなって思って(笑)。つまり、ちゃんと内容を考えていれば、書くこと自体は作業なのであまり時間はかからないということですね。手を速く動かせば、速く書けます(笑)。

ーーPull Requestにチェックリストをつくって(坂巻)

坂巻:僕も原稿を書くのは早いほうではないので、最初にある程度原稿を書いて、GitHubでPull Requestをつくります。それで、その見出しをリストにしたチェックボックスをつくって、一緒に書いておくんです。書き終わったら、チェックボックスにチェックを入れる。そういうふうに使ってます。

ーーとりあえず頭の中にあるものを全部文章に(小原)

小原:僕の場合は基本的にはアウトラインをつくって、埋めていく。僕は脳みそにとっておけないので、とりあえず文章の読みやすさとかはどうでもいいので、そのときに考えたことをわーっととりあえず吐き出して、書いてしまいますね。その段階ではちょっとおかしなことがたくさん書いてあります。で、あとになって文章を読みながら、またそれを書き直していきます。

外村:推敲しながら同じ文章内を何回も巡回するんですね。

小原:そうですね。最初に書いた「汚い文章」は、最後には残ってないです。最初のは単なるメモとして、それを見て書こうと思ったことを思い出すために使って、書き直してしまうので。自分としてはそれがいちばん楽そうだと思ってる手順です。

中村:途中で文章が止まってしまうときがありますよね。そういうときに同じようなことをやります。最初から文章を読み直して、気になるところは直していくうちに、止まっていた箇所の先がすっと出てきたりします。

ーー「書く人」が詰まったら「読む人」に変えて(外村)

外村:私もそれは同じかも。「書く人」が詰まってしまったら、今度は「読む人」になって先頭から読み直してみます。「読む人」が正しい原稿の流れをつかんだら、そこで「書く人」にスイッチして書く。そういう一人二役を細かくやっている気がします。

「まとめ」って必要?

小原:まとめを先に書いたりするのはよくやります。それをやっておかないと、書いているうちに内容が変わってきてしまって、何を書こうとしていたかブレてしまったりするので。ゴールだけ決めておけば、ちゃんと戻ってこれる。

坂巻:書く順番でいくと、冒頭と末尾(まとめ)を先に書きます。冒頭ではこの記事では何を言いたいってことを書きます。まとめはちょっとテンプレ化している(笑)。読者にちょっと言いたい一言と「この記事を参考にしていただければ幸いです」みたいな、原稿を書くやる気を出すための文章を書いてます。

中村:まとめは苦しむことがけっこうあるな。すっと書けるときは書けるんだけど。編集とやり取りして書いていることも多いかな。

杉浦:「まとめ」って記事構成的に必要ですか? 内容書くことなくて困ることが多いです。感想とかいらないじゃないですか。「楽しみですね」とか。

中村:大切なことは2回言うくらいの考えでいいんじゃないかな?

杉浦:結局、要約ですよね。いるんだろうか、これは(笑)。

坂巻:技術系の文章は要約で終わっていいと思うな。

中村:そうですね。仮に間違って理解してしまった人がそこを見て「あれ?違うじゃん」って思って読み直してもらえればいいんじゃないと思う。あっていたらそれでいいと思うし。

坂巻:そう、だから技術系文章のまとめはちょっとテンプレ化するんだと思います。リマインド、再度言っておきたい注意点とかあれば最後に書くのがいいです。LTとか、講演と一緒ですよ。「今日はこういうことを話します」から始まって、最後に「今日はこういうことを話しました」。

中村:そうね。講演の場合は、あとは「何のために話したか」とかね。求人情報が出てきたり(笑)。

(続く)

杉浦 有右嗣
杉浦 有右嗣
フロントエンド・エンジニア

業務系SIerにて主にWebサービス開発の上流工程を経験した後、大手インターネット企業に転職。ソーシャルゲームをはじめとする、モバイル向けWebサービスのフロントエンド開発を数多く経験する。フロントエンドはもちろん、サーバーサイドやネットワークの知識も豊富である。2015年株式会社ピクセルグリッドへ入社。

中村 享介
中村 享介
フロントエンド・エンジニア

デザイン事務所のWebデザイナー、Web制作会社のWebディレクターを経て、フリーランスのFlash・JavaScriptエンジニアとして独立後、株式会社ピクセルグリッドを設立。 多数のリニューアル、新規立ち上げを取り仕切った経験をもち、情報設計、デザイン、フロントエンド、サーバーサイド、ネットワークといったひと通りのWebサイト制作技術に精通する。Web制作の他にも経営、講演、執筆など幅広く活動している。

著書に『WebクリエイティブのためのDOM Scripting』(単著:毎日コミュニケーションズ、2007年4月20日)、『jQuery逆引きマニュアル』(共著:インプレス、2010年12月17日)などがある。

高津戸 壮
高津戸 壮
フロントエンド・エンジニア

Web制作会社、フリーランスを経て、株式会社ピクセルグリッドに入社。数多くのWebサイト、WebアプリケーションのHTML、CSS、JavaScript実装に携わってきた。受託案件を中心にフロント周りの実装、設計、テクニカルディレクションを行う。スケーラビリティを考慮したHTMLテンプレート設計・実装、JavaScriptを使った込み入ったUIの設計・実装を得意分野とする。 著書に『改訂版 Webデザイナーのための jQuery入門』(技術評論社、2014年11月14日)がある。 CSS Nite 2011ベストセッションにおいて、全170セッションの中から、ベスト10セッションに、CSS Nite 2013ベストセッションでは、全278セッション中、ベスト20セッションに選出。

小山田 晃浩
小山田 晃浩
フロントエンド・エンジニア

2006年よりWeb制作会社にてUI実装や運用業務を経験した後、2010年よりフロントエンド・エンジニアとして株式会社ピクセルグリッドに入社。これまでの経験の大半は大規模Webサイトの壊れにくいHTML/CSS設計、及び実装。また、SVG, Canvas, WebGLの扱いも得意としている。 外部に向けたアウトプットも積極的に行っており、カンファレンスでの講演などを多数こなしている。Tokyo WebGL Meetupの主催者。2011年から2015年まで5連続でMicrosoft MVP for IEを受賞。 著書に『Webデザイナー/コーダーのための HTML5コーディング入門』(共著:エクスナレッジ、2011年3月12日)や『CSS3デザイン プロフェッショナルガイド』(共著:毎日コミュニケーションズ、2011年5月28日)』などがある。

外村 奈津子
外村 奈津子
エディター

情報出版社に在籍中、Mac雑誌、中高年向けフリーペーパー、コラムサイト運営、健康食雑誌、グラフィック・Web技術書籍編集、IT系ニュースサイトの編集記者を経験。その後フリーランスのエディター/ライターとして独立。2011年4月より株式会社ピクセルグリッドへ入社。ピクセルグリッドが提供するフロントエンド技術情報を提供するサービス「CodeGrid」の編集を担当している。

小原 司
小原 司
UIデザイナー

紙媒体をメインに制作しているデザイン事務所で広告デザインの基礎を学ぶ。2000年に独立。化粧品関連媒体の販促物を中心に、店頭グラフィック、パッケージ、POP、グッズ立案などを担当。2007年頃からWeb媒体へのデザインにも積極的に取り組み、クロスプラットフォームアプリのデザイン、画面設計、実装に携わる。現在では紙やWebの媒体にとらわれることなく、その媒体の特長を活かしたグラフィックデザインに励んでいる。 マンセル色相環とムーン&スペンサー配色理論を採用した配色アプリ『HUE360』の開発を自身で行っている。 著書に『改訂版 Webデザイナーのための jQuery入門』(技術評論社、2014年11月14日)がある。

坂巻 翔大郎
坂巻 翔大郎
フロントエンド・エンジニア

大手ソフトウェアダウンロード販売会社、Web制作会社などで、マークアップエンジニア、プログラマ、サービス企画、ディレクターを経験。2013年、株式会社ピクセルグリッドに入社。HTML、CSS、JavaScriptなどをオールラウンドに担当。とりわけ、プログラマブルなCSSの設計、実装を得意とする。 趣味で作成したゲーム「CSS PANIC」は、JavaScriptを一切使わず、HTMLとCSSのみで実装。海外サイトで紹介されるなど話題となった。