やって技術文章書いてます2回シリーズの第1回目は、そもそもエンジニアに文章力って必要?という話からスタート。CodeGridの原稿を例に、技術文章をどのように書いているか、具体的な手順とともに、赤裸々に語ります。原稿はどういう手順で書いている?「まとめ」って必要?はじめにピクセルグリッドのスタッフは、このCodeGridという媒体のための執筆をしています。そのため、比較的技術文章を書く機会が多いと思われます。書籍執筆経験があったり、外部メディアへの寄稿を行うスタッフも少なくありません。そこで、スタッフに集まってもらい、技術文章を書くノウハウを、自分の執筆作業を振り返りながら語ってもらおうと思い立ちました。座談会に先立って、座談会に出席しなかったスタッフも含め、アンケートを行いましたので、その結果も合わせて紹介します。座談会参加者は以下のとおりです。坂巻:今日のテーマは「技術文章」ですよね。ずどさん(高津戸)って今、案件のドキュメントをまとめる業務をやってますよね。高津戸:ああ、そうですね。仕様要件に基づいてデザインが上がるんですけど、そこには書ききれていない挙動や、UIで使われている用語、それから共通の仕様などを書くんですよ。普通に文章をたくさん書いてますね。高津戸:そういう仕事でなくても、プロジェクトを進行していると、たとえばメールでも、プロジェクト管理ツールを使ってでも、クライアントとやり取りしていると、お互いにいろいろ文章でコメントし合うじゃないですか。それやっているだけで普通に1日終わる(笑)。いうときにやっぱり的確な文章を速く書けるようになったらいいなって思いますね。坂巻:わかりやすく簡潔に、っていうの大事です。長いと読む気が失せますから。中村:メールの文章はそうとう気を付けてますよ、僕は。対応が難しめのメールを書くことが多いんです。こちらにはまだ事情がわからないんだけれども、とりあえず相手が怒っているとか。いう状況で大切なことは、間違わずに相手に伝えることと、メールの長さですね。高津戸:わかりやすさということだと、ありがちなのはエンジニアにしかわからない専門用語をお客さん向けの文章で使ってしまうこととか。相手はコードのことはよくわからないのに、そういう話を中心に書いてしまうとか。コードの構造を前提に、それを知ってないとわからないような内容を展開してしまうとかね。高津戸:CodeGridの記事をやり取りしているときにもないですか(笑)?そういうこと。編集していて、「ここはprototypeだからどうのこうの、って私に言われてもね」って思うことないですか(笑)?外村:あるかも(笑)。中村:コミュニケーションの話ですよね、相手のコンテキスト、つまり持っていると思われる知識をベースにどういう回答をするかっていう。記事を執筆してても、相手のレベルはきちんと想定して、その相手にわかる言葉で書くようにしてます。小原:案件と同じで原稿にも必ず「相手」がいるからねえ。中村:ブログを書くエンジニアも多いと思うけど、僕の場合、ブログは自分に向けたメモだから(笑)。外村:そういう前提ですね。わからない人がいても「ごめんね」で済む。案件の「お客さん」や記事の「読者」に対しては、それではいけない。お客さんの場合、相手の能力ってどうやって把握するのですか?中村:打ち合わせのときなどに相手が使う言葉とか、あとは案件で上がってくる先方の要求かな。それを踏まえた上で、この人だったらこれが通じるだろうと判断してますね。坂巻:ちょっとづつレベルを上げてみたり(笑)。最初は知識がないものだと思って話すんですけど、これがわかるんだったら、これも大丈夫かな?と。中村:探ってくかんじはあるよね。あと、うまく通じていないようなら逆に下げていく。外村:メールだと相手の人数は少なめですし、内容や語彙を調整していくことができると思うんですけれど、CodeGridの原稿だと比較的大勢の人を対象としていますよね。記事を一度配信したら、調整が細かくできないという難しさもありますが。中村:それを完全にやることは無理だと思って諦めてますね。自分の想定した人に向けて書くけれど、読んだ人がそのレベルに合うかどうかはわからないので。CodeGridのパーティーをやったときに会った方々の話を聞いて、こういう人たちがいるのだなというのはわかっているので。それを元に書いています。坂巻:僕はそとさん(編集の外村)ですよ(笑)。僕が書くものに関しては、そとさんがわかったらいいなと思って書いてます。「ある程度CodeGridを読んでいて、ちょっと技術に触れている人」を対象にしたいので、そとさんくらいだといいかなあって思ってます。外村:そうなんですね(笑)。それはちょうどいいかも。【アンケート結果】業務で文章力は必要か?この座談会に先立って、文章を書くことについて社内でアンケートをとりました。エンジニア、デザイナー11名から回答をもらいました。座談会の進行に合わせて、アンケート結果も紹介していきます。0【質問2】ある(よくある、たまにある)と答えた方に聞きます。先方の仕様書やメールにツッコミをいれるときなにかドキュメントを書くときパフォーマンスチューニングでフィードバックするとき原稿など執筆での場面、ほかCodeGridの原稿を書くときWebメディアへの寄稿時ブログの執筆時ツイート文を考えるときなど同僚、クライアントや協力会社とのやり取りにおいて、課題の共有や自分の考えを提示したいときクライアントとのやり取りは圧倒的に文章が主な手段なため、その場面において、文章力を必要と考える人が多いです。あとは、納品されるドキュメントも成果物の一部であるため、けっしておそろかにできないことがわかりました。原稿はどういう手順で書いている?外村:書き方の話に入ってきたので、CodeGridの原稿を書き上げる手順を聞きたいです。ーー「書けます」と答えたときに8割が決まっている(杉浦)坂巻:アンケート見ていくと、だいたい同じなんですよね。ぃさん(杉浦)の一番目の手順の「指令を受ける」がおもしろかった(笑)。ぃさんはたぶん脳内できちんとアウトラインをつくって書くタイプだと思うのですが、脳内で構想している時間は長いんですか?杉浦:ネタによりますね。だいたい「このネタでお願いしたい」って言われて、「あ、それなら書けます」って答えたときには、もう自分の中では、8割くらいは書くことが決まっているので、あとは忘れないうちに手を動かすだけです。書き上げるまでが早いのは、仕事を手元にためておくのが嫌いだからですね。高津戸:ということはりぃさんにはネタを提供すれば、書いてもらえるのか(笑)。全員:(笑)ーーデモつくりから入ることも(高津戸)坂巻:一方、ずどさんは、アウトラインをリストでつくっておいて、Markdownで書いていきながら考えると。高津戸:ああ、だいたいそうですね。スライドとかをつくるときも一緒ですね。見出しレベルだけ書くのではなくて、書けるところから書いてしまう?高津戸:うーん、そのあたりはマチマチですね。見出し書いて、少しだけ書くこともありますし、見出しも内容も書いてしまうこともあります。あとは、たとえばCSSのプロパティを解説するみたいな記事だと、そもそも構成を考える前にデモをつくっていろいろ検証しますね。その検証結果をさらに仕様と突き合わせて理由を調べることをやっていることも多いです。坂巻:僕はこの機能を説明するためにはどういったデモがわかりやすいかってことを考えなくちゃいけないんで、デモは文章を書いたあとで考えますね。わかりやすいデモができたなと思ったら、それを元に解説を書いたりしています。ーー頭の中で考えてから一気に書くことも(中村)中村:僕はデモが入ってくる記事はあまり書くことはないのですが、技術系の記事を書くときは何かしら実務で使ったものを解説することが多いので、デモ作成に時間を使うことはまずないですね。記事を書くときに、もう一度検証はもちろんしますけれど。外村:構成はどうやって考えてます?中村:ちゃんとしたアウトラインはつくってなくて、箇条書きをわっとつくります。この箇条書きは、構成というよりは、自分のハマったポイントや、落としてはいけないこと、書きたいことを入れていきます。その順番を入れ替えたり、これは全体の流れから外れるよねというものを除外して全体がひとつのストーリーになるように考えていきます。テーマが違うと書き方も変わります?中村:「ピクセルグリッドの仕事術」シリーズを書くときなどは、頭の中でどういうことを書くかずっと考えてます。そのままわっと書けることもあるし、書けないときは、やはりまず落としてはいけないことを先行して書いてしまいます。あとは全体がうまくつながるようにしながら、書き加えていって終わりというかんじですかね。外村:全体をひとつのストーリーにしていく論理展開で苦しむことはあまりないんですか?中村:論理展開はそんなに苦しまないですけど、僕がいちばん苦しんでいるのは脳内で構成しているときで、期間的にもいちばん長いです。ま、だいたい原稿を出すのが遅いので、編集の人はわかっていると思うんですけど(笑)。外村:じゃあ、書くときにはもう流れはほぼ決まっている?中村:もちろん書きながら変えるときはあるけれど、だいたい決まっていて、ほぼできている状態になってから書き始めます。知り合いの元編集者で本の執筆をなさる方がいるんですよ。その方は原稿の執筆がものすごく早い。その方が言っていたことは、180ページくらいの本1冊の分を内容を頭で考えていて、執筆時は2日くらいホテルにこもって全部書いてしまうそうです。すごいなって思って(笑)。内容を考えていれば、書くこと自体は作業なのであまり時間はかからないということですね。手を速く動かせば、速く書けます(笑)。Requestをつくります。それで、その見出しをリストにしたチェックボックスをつくって、一緒に書いておくんです。書き終わったら、チェックボックスにチェックを入れる。いうふうに使ってます。ーーとりあえず頭の中にあるものを全部文章に(小原)小原:僕の場合は基本的にはアウトラインをつくって、埋めていく。僕は脳みそにとっておけないので、とりあえず文章の読みやすさとかはどうでもいいので、そのときに考えたことをわーっととりあえず吐き出して、書いてしまいますね。その段階ではちょっとおかしなことがたくさん書いてあります。あとになって文章を読みながら、またそれを書き直していきます。外村:推敲しながら同じ文章内を何回も巡回するんですね。最初に書いた「汚い文章」は、最後には残ってないです。最初のは単なるメモとして、それを見て書こうと思ったことを思い出すために使って、書き直してしまうので。自分としてはそれがいちばん楽そうだと思ってる手順です。中村:途中で文章が止まってしまうときがありますよね。いうときに同じようなことをやります。最初から文章を読み直して、気になるところは直していくうちに、止まっていた箇所の先がすっと出てきたりします。ーー「書く人」が詰まったら「読む人」に変えて(外村)外村:私もそれは同じかも。「書く人」が詰まってしまったら、今度は「読む人」になって先頭から読み直してみます。「読む人」が正しい原稿の流れをつかんだら、そこで「書く人」にスイッチして書く。いう一人二役を細かくやっている気がします。「まとめ」って必要?小原:まとめを先に書いたりするのはよくやります。それをやっておかないと、書いているうちに内容が変わってきてしまって、何を書こうとしていたかブレてしまったりするので。ゴールだけ決めておけば、ちゃんと戻ってこれる。坂巻:書く順番でいくと、冒頭と末尾(まとめ)を先に書きます。冒頭ではこの記事では何を言いたいってことを書きます。まとめはちょっとテンプレ化している(笑)。読者にちょっと言いたい一言と「この記事を参考にしていただければ幸いです」みたいな、原稿を書くやる気を出すための文章を書いてます。中村:まとめは苦しむことがけっこうあるな。書けるときは書けるんだけど。編集とやり取りして書いていることも多いかな。内容書くことなくて困ることが多いです。感想とかいらないじゃないですか。「楽しみですね」とか。中村:大切なことは2回言うくらいの考えでいいんじゃないかな?杉浦:結局、要約ですよね。いるんだろうか、これは(笑)。坂巻:技術系の文章は要約で終わっていいと思うな。仮に間違って理解してしまった人がそこを見て「あれ?違うじゃん」って思って読み直してもらえればいいんじゃないと思う。あっていたらそれでいいと思うし。坂巻:そう、だから技術系文章のまとめはちょっとテンプレ化するんだと思います。リマインド、再度言っておきたい注意点とかあれば最後に書くのがいいです。LTとか、講演と一緒ですよ。「今日はこういうことを話します」から始まって、最後に「今日はこういうことを話しました」。講演の場合は、あとは「何のために話したか」とかね。求人情報が出てきたり(笑)。有右嗣フロントエンド・エンジニア業務系SIerにて主にWebサービス開発の上流工程を経験した後、大手インターネット企業に転職。ソーシャルゲームをはじめとする、モバイル向けWebサービスのフロントエンド開発を数多く経験する。2015年株式会社ピクセルグリッドへ入社。フロントエンドはもちろん、サーバーサイドやネットワークの知識も豊富である。享介フロントエンド・エンジニアデザイン事務所のWebデザイナー、Web制作会社のWebディレクターを経て、フリーランスのFlash・JavaScriptエンジニアとして独立後、株式会社ピクセルグリッドを設立。多数のリニューアル、新規立ち上げを取り仕切った経験をもち、情報設計、デザイン、フロントエンド、サーバーサイド、ネットワークといったひと通りのWebサイト制作技術に精通する。Web制作の他にも経営、講演、執筆など幅広く活動している。Scripting』(単著:毎日コミュニケーションズ、2007年4月20日)、『jQuery逆引きマニュアル』(共著:インプレス、2010年12月17日)などがある。壮フロントエンド・エンジニアWeb制作会社、フリーランスを経て、株式会社ピクセルグリッドに入社。Webサイト、WebアプリケーションのHTML、CSS、JavaScript実装に携わってきた。受託案件を中心にフロント周りの実装、設計、テクニカルディレクションを行う。スケーラビリティを考慮したHTMLテンプレート設計・実装、JavaScriptを使った込み入ったUIの設計・実装を得意分野とする。jQuery入門』(技術評論社、2014年11月14日)がある。2013ベストセッションでは、全278セッション中、ベスト20セッションに選出。晃浩フロントエンド・エンジニア2006年よりWeb制作会社にてUI実装や運用業務を経験した後、2010年よりフロントエンド・エンジニアとして株式会社ピクセルグリッドに入社。これまでの経験の大半は大規模Webサイトの壊れにくいHTML/CSS設計、及び実装。WebGLの扱いも得意としている。外部に向けたアウトプットも積極的に行っており、カンファレンスでの講演などを多数こなしている。Meetupの主催者。プロフェッショナルガイド』(共著:毎日コミュニケーションズ、2011年5月28日)』などがある。グラフィック・Web技術書籍編集、IT系ニュースサイトの編集記者を経験。その後フリーランスのエディター/ライターとして独立。2011年4月より株式会社ピクセルグリッドへ入社。紙媒体をメインに制作しているデザイン事務所で広告デザインの基礎を学ぶ。販促物を中心に、店頭グラフィック、パッケージ、POP、グッズ立案などを担当。2007年頃からWeb媒体へのデザインにも積極的に取り組み、クロスプラットフォームアプリのデザイン、画面設計、実装に携わる。現在では紙やWebの媒体にとらわれることなく、その媒体の特長を活かしたグラフィックデザインに励んでいる。マンセル色相環とムーン&スペンサー配色理論を採用した配色アプリ『HUE360』の開発を自身で行っている。jQuery入門』(技術評論社、2014年11月14日)がある。翔大郎フロントエンド・エンジニア大手ソフトウェアダウンロード販売会社、Web制作会社などで、マークアップエンジニア、プログラマ、サービス企画、ディレクターを経験。2013年、株式会社ピクセルグリッドに入社。HTML、CSS、JavaScriptなどをオールラウンドに担当。プログラマブルなCSSの設計、実装を得意とする。PANIC」は、JavaScriptを一切使わず、HTMLとCSSのみで実装。海外サイトで紹介されるなど話題となった。特定商取引法に基づく。