社内に「テクニカルライティング」のチームがある理由　「プロダクトの品質」だけでなく「ドキュメントのわかりやすさ」もポイントに　

「テクニカルライティング」の専門チーム

堀越良子氏（以下、堀越）：それでは「LINEの開発者向けドキュメントを支える『テクニカルライティング』の専門チーム」というセッションを始めます。まずは私たち2人の自己紹介をいたします。

このセッションの前半を担当します、テクニカルライターの堀越良子と申します。私はもともとWeb制作会社でインフラエンジニアをしていましたが、その時に書いた技術書が縁で、2020年からLINEでテクニカルライターという仕事をしています。

今日は、このテクニカルライターという職業について、みなさんにお話ししようと思っています。続いてロマンさん、自己紹介をお願いします。

ロッサ・ロマン（以下、ロマン）：ロマンです。フロントエンドエンジニアをやっています。今日は後半のセッションを担当しています。LINE Developersサイトの開発も担当しています。

私はドイツ生まれで、日本には6年ぐらい前に来ました。Vue.jsが好きで、最近とてもYouTubeにハマっています。今日は、テクニカルライティングチームの中にいるエンジニアの役割について、話していきたいと思います。よろしくお願いします。

堀越：ありがとうございます。ではまず、このセッションの構成についてお話しします。この40分のセッションでは、前半を私、テクニカルライターの堀越が、テクニカルライターとは何か、であったり、自社にテクニカルライターがいるとこんなに良いことがある、というお話をしていきます。

そしてバトンタッチして、後半はエンジニアのロマンさんが、テクニカルライティングのチームでエンジニアがどんな役割を果たしているのかをお話しします。

前半と後半、それぞれ終わったら、最後に私が再び出てきて、少しセッションのまとめをお話しする予定です。それではロマンさん、また後半でお会いしましょう。

テクニカルライターとは何か

それでは前半のテクニカルライターのパートを始めていきたいと思うのですが、先に1つ、みなさんに質問をさせてください。みなさん、テクニカルライターって何だかご存じでしょうか。ここ1年くらいで、少しずつ知名度が上がってきた職業なので、人によっては「知っているよ」あるいは「名前くらいなら聞いたことがあるよ」という方もいると思うのですが、ほとんどは「テクニカル…何？　ライター？」という感じだと思います。

テクニカルライターが日々どんなふうに仕事をしているのかは、詳しくこの後お話ししますが、まずは、テクニカルライターがいる時といない時で、世界はこんなに違うという差をお見せしたいと思います。

テクニカルライターは何をしているのか。つまり、テクニカルライターがいる世界といない世界では、どんな違いがあるのかをお見せします。

こちらはLINEのエンジニアが書いた、とあるAPIに関するドキュメントです。実際のLINEの社内Wikiから持ってきました。リッチメニューエイリアスというものをcreateするAPI、それからdeleteするAPIの使い方が書いてあります。

エンドポイントのパスが何で、メソッドは何で、リクエストヘッダーにはこれが必須、成功すると200が返ってきて、失敗した時は400が返ってくるというように、必要最低限の情報は押さえてあります。これがテクニカルライターがいない世界のドキュメントです。

では、テクニカルライターがいる世界を見てみましょう。テクニカルライターがいる世界では、ドキュメントはこうなります。これは先ほどの左側、リッチメニューエイリアスというものをcreateするAPIのリファレンスです。

このAPIをどんなふうに叩けばリッチメニューエイリアスが作れるのか、という必要最低限の情報に加えて、リッチメニューエイリアスを作りたかったら、その前にリッチメニューというものを作っておいたり、画像をアップロードしておいたりという事前準備が必要ですよ、という説明も加わっています。具体的なリクエストの例やエラーレスポンスの例などもあって、初めて読む人に、より親切な内容になっています。

そしてこちらは先ほどの右側、リッチメニューエイリアスをdeleteするAPIのリファレンスです。リッチメニューエイリアスをdeleteするAPIといわれても、そもそもせっかく作ったリッチメニューエイリアスをどういう時に削除する必要が出てくるんだろう、という疑問はきっと浮かんでくると思うんですね。

実は、リッチメニューエイリアスって作れる数に1,000件という上限があります。上限に達するともう作れなくなってしまうので、その場合はもう要らなくなった既存のリッチメニューエイリアスを削除する必要が出てくるんです。そういう説明も、加わっています。

そしてテクニカルライターがいる世界では、それぞれのAPIの使い方、APIリファレンスだけではなく、APIとAPIを組み合わせるとどんなことができるのか、というドキュメントも生まれます。

みなさん、先ほどのリッチメニューエイリアスをcreateするAPI、それからdeleteするAPIがあるよ、という説明だけでは、おそらくそれによって何ができるのかまではわからなかったと思うんですね。

でもこちらのドキュメントでは、リッチメニューエイリアスを使うとタブ切り替えのように複数のリッチメニューを簡単に切り替えられますと書いてあり、イラストも相まって、何ができるのかが一目でわかります。

これがテクニカルライターがいる世界といない世界の違いです。ではここからは、そんなテクニカルライターについて、詳しくお話をしていきます。

テクニカルライターの役割

そもそも、テクニカルライターとはどんな役割を負っているのでしょうか。一般的には、テクニカルライターは取扱説明書を書く、という役割を負っています。みなさんが洗濯機や冷蔵庫などを購入した時、「このボタンを押すと洗濯できます」「この設定をONにすると冷蔵庫の温度が下がります」など、いろいろ使い方が書いてある取扱説明書が付いてきたと思います。あの取扱説明書を書いているのが、テクニカルライターです。

では、洗濯機も冷蔵庫も作っていないLINEでは、テクニカルライターはどんな役割を負っているのでしょうか。

LINEでは、テクニカルライターは外部の開発者向けドキュメントを書く、という役割を負っています。外部の開発者向け技術ドキュメント、と言われてもピンとこないと思うので、もう少し詳しく説明していきます。

例えば、こんな画面を見たことがあるのではないでしょうか。ネットショップや会員制のサイトなどで、メールアドレスとパスワードを入力してログインすることもできるが、面倒くさいのでLINEやFacebook、Googleのアカウントでログインできる、というボタンですね。

みなさんがこのLINEログインのボタンを「自社のサイトにも実装したい」と思ったとします。でもきっと「どうやるんだろう」「このボタンを実装する方法は何だろう」となりますよね。

そんな開発者のために、LINEのテクニカルライターは、LINEログインをはじめとするさまざまなLINE APIの使い方、実装方法を書いたドキュメントを、こちらのサイトで提供しています。左側がLINE Developersサイト、右側がLINE CLOVAに特化したCLOVA Developer Center βです。

こうしたLINE APIに関する技術ドキュメントを、私たち、LINEのテクニカルライティングの専門チームで書いています。現状は、私を含めてテクニカルライターが6人と、このセッションの後半を担当してくれるエンジニアのロマンさんが1人、合計7人のチームです。では、この7人のメンバーでLINE APIのドキュメントをどんなふうに書いているのか、というお話をしていきます。

LINE APIのドキュメントはどう書かれているのか

LINE APIのドキュメントはどのように書かれているのか。まず、基本的にドキュメントは英語と日本語で同時に書かれて、同時にリリースされます。台湾の開発者向けに、一部のドキュメントは中国語でも提供されています。

これらのドキュメントを書く時には、社内の開発者から「こういう機能がリリースされる」という仕様についてのインプットが行われます。

ミーティングの時間をもらって30分程度でインプットしてもらうこともあれば、先ほどお見せしたような仕様が書かれた社内のWikiを渡されて、それを読んで書くこともあります。

最初のドラフトを書くライターが、日本語が得意であれば日本語で書いてからチーム内で英訳しますし、逆に英語が得意なライターなら、英語で書いてからチーム内で日本語に翻訳します。いずれのケースでも、翻訳はどこかにお願いしているわけではなく、私たちのチームの中で、ライティングも翻訳も行なっています。

実際にドキュメントをどのように書いているのかというと、Visual Studio Codeを使ってMarkdownで書いています。画面上に今表示されているのが、実際の原稿です。

何ヶ所か青い波線だったり黄色い波線だったりが表示されていると思うのですが、これはValeやtextlintという、自動で内容の校正をしてくれるツールです。

「文法上こういう書き方をすべきだよ」であったり「このサービス名称は正しくはこういう表記だよ」のように、事前に定めておいた書き方のルールに沿っていろいろな指摘をしてくれます。

ドキュメントを書いたら、ローカル環境で動かしてみて、実際の見た目で確認をします。「ここはこういう見た目になるんだ。じゃあ図があったほうがいいかもしれない」あるいは「箇条書きにしたほうがいいかもしれない」というように、実際の見た目を確認しながら原稿を少しずつ直していきます。

できあがったそれをGitHubにプッシュして、プルリクエストを作成します。プルリクエストを作ると何が起きるかというと、自動でビルドチェックやリンク切れのチェックや先ほどの自動校正チェックなどが走ります。

左側はValeチェック。つまり、自動校正のチェックで「こういう書き方をしてはいけません」という部分が引っ掛かって、赤いバツで怒られています。Markdownの構文が間違っていれば、ビルドチェックで引っ掛かるし、このプルリクエスト内で既存のページを削除した結果、他のページからのリンク切れが発生したりすると、リンクチェックで引っ掛かるので、何か問題があれば必ずここで気づくようになっています。大丈夫だったら、右側のようにオールグリーンの表示になります。

そして自動のチェックが走ると同時に、Sandboxというブランチごとの動作確認用のサイトも生まれます。作成したドキュメントはチーム内でレビューも行いますが、そのプロダクトの責任者やその機能を作った開発者にも、本番とまったく同じ見た目のSandboxで確認してもらいます。

そこで「ここの説明は仕様に対して間違っている」や「ここの部分はもうちょっと丁寧に説明してほしい」などの指摘があれば、プルリクエスト上でコメントしてもらって修正し、再びSandboxで確認してもらいます。

最終的に「これでOKです、出していいですよ」という状態になったら、マスターブランチにマージして、CI／CDツールが自動で走り、そして本番環境へリリースされます。

もう一度環境を整理すると、まずはみなさんから見える本番の環境があります。そしてその後ろ側にRCやBeta、Sandboxなど動作確認用の環境があり、我々の手元にはローカルの環境があります。これらの環境で順番に確認をしていって、「問題ない」となってから本番の環境にリリースされます。

こうやってリリースされると、みんなで「リリースされたー！」と喜んでいます。「ドキュメントってどのくらいのペースでリリースしているんですか」っていう質問をよくいただくのですが、今年に入ってからのリリース回数を確認したところ、平均して月に25回ほどリリースしていました。

営業日が月に20日だと思うので、1日1回以上、だいたい1.25回くらいのペースでリリースをして、少しずつドキュメントの改善を進めています。ちなみに今年（2021年）は月に25回程度なのですが、去年（2020年）は月に19回だったので、ドキュメントを改善していくペースは着実に上がっていることがわかります。

さて、こんな流れで我々はドキュメントを日々書いたり直したりしているのですが、次はテクニカルライターを、あるいはテクニカルライティングの専門チームを会社の中に持つことで「こんないいことがありますよ」というお話をしていこうと思います。

テクニカルライティングのチームを社内に持つメリット

テクニカルライティングのチームを社内に持つことのメリットとは。テクニカルライターにドキュメント作成を任せると、まずはドキュメントの品質が上がります。仕様についての説明だけではなく、このAPIはどんなふうに使えばいいのか、つまずきやすいポイントはどこかなど、開発者が開発する時に知りたい内容を網羅して、わかりやすいドキュメントになるよう我々は日々工夫を重ねています。

我々は開発者からの問い合わせを受けるサポートチームとも連携していて、よく問い合わせを受ける箇所、つまりドキュメントを読んでもわからなかったと思われる箇所については、日々改修を行なっています。これは他の仕事の片手間ではなく、ドキュメントのライティングを専門としているチームだからこそできることです。

ドキュメントは、みなさんご存じだと思うのですが、とっても重要なんです。自分たちが作ったプロダクトを「開発者に使ってほしい」と思ったら、プロダクトの品質を高めることは、もちろん重要です。そしてそれと同じくらい、わかりやすいドキュメントがあることが重要です。

でも大事だとはわかっていても、どうしても開発のほうが優先になってしまう、ドキュメントが置いてきぼりになっていってしまうというのは、よくあることです。

開発者に「ドキュメントも書いてくださいね」とお願いしたとしても、開発の能力とライティングの能力は、また別物です。開発者みんながライティングが好きだったり、得意だったりするわけではありません。

また、その機能を開発した開発者自身だからこそ、その機能についてまだ何も知らない人のためのドキュメントを書くのは難しかったりします。

テクニカルライターにドキュメント作成を任せることで、ドキュメントを読む側にもメリットがあるし、開発者側も本来やるべき開発にフォーカスできるというメリットがあります。

では次に、どんな人がこのテクニカルライターという職業に向いているのか、についてお話ししていこうと思います。

どんな人がテクニカルライターに向いているか

どんな人がテクニカルライターに向いているのか。LINEにおいてテクニカルライターに必要なスキルはいくつかありますが、一番大事なのは、渡された仕様を理解できるだけの技術的な素養があることです。これはMustだと、我々は思っています。

続いて、わかりやすいドキュメントを書けるライティングのスキルがあること。そして最後に、これはMustではなくてNice to Have、あったらいいなというレベル感ですが、日本語と英語のうち、自分が得意でないほうの言語の読み書きスキルも必要となってきます。

日本語と英語、両方ともネイティブレベルで書ける必要まではないのですが、少なくとも、自分が書いた日本語とチーム内で他のライターが翻訳してくれた英語が、どちらも同じことをいっているのかを確認できるだけの読むスキル、あるいは他のライターが書いた英語を日本語に翻訳できるだけのスキルが必要です。これは英語のライターの場合も同様ですね。

ではこの3つの中で、どれが一番重要かというと、我々は一番左側の「渡された仕様を理解できるだけの技術的な素養があること」が一番大事だと思っています。なぜかというと、特定のプロダクトについてわかりやすいドキュメントを書くためには、その裏側にある技術を理解する必要があるからです。

例えばLINEログインのドキュメントを書こうと思ったら、裏側にあるOAuth 2.0という技術を理解する必要があります。また、LINEでボットからメッセージを送れるMessaging APIというプロダクトがあるのですが、その中のFlex Messageに関するドキュメントを書こうと思ったら、こちらもやはり裏側にあるCSS Flexboxという技術を理解しなければいけません。

ちゃんと理解していないまま、開発者からもらった仕様書を体裁だけ整えたきれいな文章にすると、パッと見はきれいでも、よく読むと使い方が結局わからないという残念なドキュメントが生まれるだけなんですね。

LINEにはたくさんのプロダクトがあります。ですので、LINEでテクニカルライターをすることになったら、必然的にいろいろな技術について積極的に学んでいくことになります。書くことが好きで、技術について学ばなければならない環境を「楽しい」と思える人が、LINEのテクニカルライターには向いていると思います。

テクニカルライターの専門チームを作るには

さて、ここまでお話ししてきて「テクニカルライターいいな」「うちの会社でもテクニカルライターを雇って専門チームを作りたいなあ」と思われた方もいると思います。

実は今、多くのIT企業がテクニカルライティングのチームを作ろうとしていて、テクニカルライターを探しています。「LINEではどんなふうにやっているのかお話を聞かせてください」と声をかけられることも増えてきました。

でも、IT系のテクニカルライターは、そんなに昔からある職業ではないので、そのへんにたくさんいないんですね。しかも技術の素養があるテクニカルライターとなると、簡単には見つかりません。

そんな時は、会社の外ではなく、会社の中にいる開発者に目を向けてみてください。開発者の中には、書くことが好きで個人的に技術書を書いている人や、技術記事を寄稿している人、技術ブログを書いている人が一定数います。そういう人に「テクニカルライターにジョブチェンジしてドキュメントを書くことに専念してもらえないか」と相談してみるのも、1つの方法です。

では、前半のパートはおしまいです。ここからは後半のロマンさんにバトンタッチして、そんなテクニカルライティングの専門チームで、エンジニアがどんな役割を果たしているのかを聞いていきたいと思います。

（後半につづく）