本コーナーでは技術へのタッチポイントを増やすことを目標に、各分野で活躍されている方をお迎えします。

今回はテクニカルライティングをテーマに堀越さんにインタビューします。書く技術の一端に触れて仕事や趣味に活かしてみませんか。

【話し手】
堀越 良子（HORIKOSHI Yoshiko）

LINE ではたらくテクニカルライター。技術書典で『DNS をはじめよう』などのインフラ入門書を執筆。ねこが好き。

Twitter @mochikoAsTech
GitHub mochikoAsTech
URL https://mochikoastech.booth.pm/

書く仕事

日高： 今のドキュメントを書くお仕事とは、どのように出会ったのでしょうか。

堀越： 私のキャリアはPHPエンジニアから始まっています。そのあと広報をやって、今の仕事の前はインフラエンジニアを7年ほどしていました。当時、仕事をしながら個人として技術書を執筆していたのですが、過去の自分に読ませるような気持ちが大きかったです。技術書を読んだ方からイベントでお声がけいただいて今のテクニカルライターというキャリアに触れました。

日高： エンジニアから大胆な変化ですがキャリアチェンジにあたって不安はありませんでしたか。

堀越： あまり抵抗がない性格なのかもしれません。その時々で求められる役割にチャレンジしてきた感覚ですね。ただエンジニアとしてのものづくりはずっと楽しいなと感じていました。

日高： エンジニアも書く仕事ですが、コードだけでなくドキュメントを扱うことも増えていますね。個人的にはSlackやTeamsなどでテキストコミュニケーションを取ることも多く、伝えるためのライティングがより身近になったと感じています。

堀越： 私も以前はドキュメントを書くことが仕事になるとは思っていなかったですね。話を聞くうちに興味が出て、現職のLINEでテクニカルライターになり、今は開発者向けのドキュメントを書く形でプロダクトに携わっています。

テクニカルライティングとは

日高： テクニカルライティングではどんなことが仕事の対象になってくるのでしょう。

堀越： 書く前に機能を理解しなければいけません。たとえば「LINEログイン」のドキュメントを書くにはOAuth 2.0といった認可のしくみ、Messaging API の「Flex Message」ではCSS Flexboxなどレイアウト構造のための技術への理解が求められます。

日高： 多様な技術背景が前提だと。

堀越： そうなんです。対象を理解しないまま書くと、きれいなだけで何もわからない残念な文章ができてしまう。仕事では技術理解の部分が一番大変かもしれません。

日高： エンジニアの仕事も専門領域に分化しているので横断的に覚えるのはキツそうです。

堀越： 先週はサーバサイドの技術を調べて、今週はフロントエンドの仕様を学んで、と振り幅の激しいときもありますね。開発者が用意してくれたAPIの仕様書があっても、鵜呑《うの》みにせず実際に使って挙動の確認もしています。

日高： そのまま仕様を書き起こしてねという仕事ではない。

堀越： はい。IT業界におけるテクニカルライターは、文章を書くスキルよりも先に、仕様を理解するための技術の素養が必要だなと感じています。それからQA（Quality Assurance、品質保証）や開発者（APIなどのユーザー）サポートの人たちとも距離が近い仕事です。

日高： フィードバックが各所からくるんですか？

堀越： そうですね、開発者からこういう問い合わせが多いので、ドキュメントの表現を修正してほしいという依頼もあります。

日高： 世の中に出してから改善できるのはいいですね。紙に印刷してしまうとなかなか修正がきかないので困ってしまって。

堀越： APIや機能は日々改善されているので、「⁠書いてあるとおりに設定したが動かない」などの問い合わせを受けることもあるんです。そういうときはできるだけ早く確認と修正をするよう心がけています。

全員に最後まで読んでもらうのが成功ではない

日高： 正しい使い方を誘導するのもテクニカルライティングの一部なんでしょうか。

堀越： うーん、ドキュメントの役割は半分ぐらいかもしれません。残りの半分はSDK（Software Development Kit）の提供といった開発者サポートが受け持っていると思います。使い慣れた言語で便利なSDKが提供されていれば、ゼロから開発するよりも断然開発しやすいからです。

日高： ドキュメントがあるから大丈夫とはならないわけか。たしかにそのとおりですね。新たに機能やAPIが加わるとき、伝え方で工夫できる点はありますか？

堀越： 一例ですが、これがどんな機能かという説明の前に、これによって今までできなかった何ができるようになり、どううれしいのか、というメリットを提示するようにしています。さらに言うとメリットよりも前に「この機能追加はどんな人に関係するのか」が伝わっている必要があります。誰に影響がある話なのかわかれば、それ以外の人はドキュメントを読まずに済ませちゃっても問題ないですから。

日高： 読んで損したとか時間を無駄にした気分にならないほうがいいと。

堀越： そうですね（笑⁠）⁠。一般的な小説やエッセイとテクニカルドキュメントの大きな違いは、全員に最後まで読んでもらうのが成功とは限らない、という点なんです。分岐で対象者を絞っていって読者が「この情報は自分には必要ない」と判断した瞬間に離脱できれば、最後まで無駄に読んでもらうよりずっといいんですよね。

日高： それは大きな違いだと感じます。私も端から端までリファレンスを読むケースはほとんどありません。

堀越： ですので本当にその情報を求めている人が読んでくれて、その機能を使ってみるといった次の行動につながれば、テクニカルライティングとしては大成功なんです。

日高： 必要な人だけがドキュメントを読んでねという価値観がおもしろい。広めるだけじゃなくて情報を整理する役割だなと。

誤解のない伝え方

堀越： ええ、テクニカルドキュメントでは表現や構造を工夫して、適切な読者に情報を届ける点を意識しています。

日高： 参考にしている事例とかもあるんですか？

堀越： 携わっているLINE Developersのドキュメントもわかりやすい内容になるよう努力していますが、Stripeの開発者向けドキュメントもよくできていますね。いろいろなドキュメントを見て、欲しい情報に迷わずたどり着けるにはどうしたらいいんだろう、と日々考えています。

日高： 堀越さんからみてライティングの注意点などはありますか？

堀越： 書くことについての悩みは、業種を問わずほとんどの人が持っていらっしゃると思います。エンジニアという職種をとってもコミットメッセージで悩むことはよくありますし。

日高： コミット時は悩んだ末にupdated〜で終わらせることも多いです（笑⁠）⁠。

堀越： やりがちですよね。そういうときは変更後のコードを見ただけでは読み取れない背景を含めるといいですよ。

日高： 「⁠仕様変更の結果を反映した」などでしょうか。

堀越： ええ、そうですね。「⁠わかりやすくするために処理手順を統一した」などのコミットメッセージでも情報量が増えていいと思います。誰かがあとで見たとき、変更の経緯というのは明確でないケースが多いんです。のちのち「なんでこんな変更したの？」となったときに、理由が読み取れる状態が理想です。

日高： 書いた本人だけが理解している暗黙的な事柄を明文化しましょうと。このあたりの技術的背景は今だとDesign Docといった設計文書でコミュニケーションを取るシーンも多いですよね。

読者は誰なのか

堀越： ライティングのスキルが求められる場面は昔より増えていると感じます。私は開発者向けのドキュメントを書くのがメインの仕事ではありますが、社内での告知やWikiのレビューを依頼されることもありますよ。

日高： おもしろい現象ですね。告知は普段から担当していないと正しく書けているかという不安も大きそう。

堀越： 対象者が広い場合や緊急性が高い場合など、普段と違った文章を書くときには自分たちの中では常識になっている前提の情報を書き漏らすことがよくあります。

日高： 大事な前提が伝わらないので、ちぐはぐした印象を読み手が受け取る？

堀越： はい。ですので、誰に向けた告知なのかわかるよう冒頭に対象者を書きましょう、などと指摘することが多いですね。誰向けの連絡か、というのは重要な構成要素ですが、告知したい人にとっては明確なので書き飛ばす場合があります。そういうとき、読み手は「誰が対象者かわからないな」と悩んでしまうんです。

日高： 頑張って読んだけど実は他部門向けの話だったとかは身に覚えがあります。

堀越： どんなケースでも応用できるライティングのテクニックもあります。よく使うのは日本語で書いたものをいったんDeepLなどの機械翻訳にかけてみるやり方です。日本語を英語に翻訳した結果、書き飛ばしていた暗黙的な主語が見つかるんです。

日高： 「⁠私」や「あなた」といった誰に何をしてほしいかという情報ですね。

堀越： 日本語では主語が省略されがちなんですが、英語に翻訳するとIであったりYouであったり、省略した主語を補完してくれます。そこで意図しない主語が出ていれば誤解しやすい文章だとわかります。

日高： 思い込みで書いていて、読者が勘違いしそうなパートを発見できるわけですね。

堀越： そうですね。思い込みというと個人の問題と感じがちですが、社内という切り口でもチームや部門によって共有する背景や文化の範囲が違います。それぞれには暗黙的な相互理解があって接点が減るほど共通範囲が薄くなっていく感覚です。

日高： その暗黙的な相互理解を上手に文章にできていれば、わかりやすいドキュメントだと。

堀越： はい。そのためには自分の書いたドキュメントを一度忘れてまっさらな気持ちで読みなおす……ことができればいいんですが、なかなかうまくいかないと思います。

日高： テクニカルライティングの大変さが伝わってきました。

堀越： 第三者の視点をいきなり作るのは難しいので、機械翻訳といったツールを使う以外にも『日本語スタイルガイド』[1]を参考にしたり、自動校正ツールを使ったり、ほかの人にレビューしてもらったりとさまざまな方法で確認しています。

開発者とドキュメントの関係を身近にしたい

日高： SDKやAPIのリファレンスといったテクニカルドキュメントを読んだことがない開発者はほとんどいないはずですが、実は読むときって困っているケースが多いですよね。

堀越： ですよね。読みにきている時点ですでにちょっと困ったり怒ったりしているので、気持ちの余裕が少ない。だからこそテクニカルドキュメントには、そのとき役に立つことがはっきり書かれていてほしいと思うはずです。

日高： そうなんです。ドキュメントのわかりやすさと使いやすさは関連していそうと思います。

堀越： でもはっきり書くのって善し悪しがあるんですよね。たとえば「AとBはできる。Cはできない」と書くと「Cはできない」は明確でも、その後の仕様変更でDやEができるようになったときに、（⁠それを反映する前のドキュメントの）読み手が「DやEはできるの？ できないの？」と混乱してしまいます。ドキュメントのメンテナンスが追いつかなくてもできるだけ誤解を招かないよう、あえて「AとBができます」という端的な書き方にすることはあります。

日高： あ、そうか。開発者がドキュメントをメンテナンスしていれば齟齬《そご》はないけど、更新担当が違うと多少ずれるという話ですか？

堀越： それは極力なくすように努めていますが、工数が有限な中ではドキュメントのメンテナンスが行き届かなくなる実情があるという話ですね。詳細に書くことでドキュメントのメンテナンスコストが上がり、その結果変更が行き届かなければ、誤った情報で読み手である開発者が混乱してしまいます。

日高： よかれと記載を増やしても将来の負債になるケースもあるのか……。

堀越： さじ加減が難しいといつも感じています。その苦労の分、担当したLINEのドキュメントが良くできていると言われたらうれしさもひとしおなのですが。

日高： OSSではドキュメントもコントリビューターに支えられている領域な気がしますね。見つけたチュートリアルなどが古いまま放置されているのを見ると悲しい気持ちになることもあるんです。

堀越： ソフトウェアとテクニカルドキュメントは密接に関わっています。私は今テクニカルライティングを専門にしていますが、こんなふうにテクニカルライターとの作業分担が可能な環境にはない方もまだまだ多いのではないかと思います。

日高： 今日お話を聞いた中でもエンジニアの立場からできることは多そうだと感じました。

堀越： 技術を理解してさえいればライティングやコミュニケーションのスキルは訓練しだいで伸ばせると思うんですよね。

日高： たしかに最新技術を覚えるよりもライティングを覚えるほうが難易度は低い。すでにある程度はできているとも言えるし。

堀越： はい。台所にまったく立ったことがない「文章を書くのがうまい人」よりも、料理人の方が書いたレシピのほうがきっと参考になると思うんです。仕事でも趣味でももっと書くことを楽しんでもらいたいなと思っています。実は書くことを身近に感じてほしくて、エンジニア向けにLINE Technical Writing Meetupというミートアップをオンラインで毎月開催しています。

日高： 興味を持った方は参加してみてください。今日はドキュメントのノウハウをたくさんいただきました。ありがとうございました。