📝

テクニカルライターがプロダクトやチームに貢献できること

2023/12/30に公開

Solo Technical Writer のやざきです (Solo という響きがお気に入り)。株式会社ソラコムで、SORACOM Users (通称、SORACOM ユーザーサイト) というサイトの管理をしています。「ユーザー」と書いていますがれっきとした公式サイトです。

先日、「ドキュメントを誰のために書いていますか」という記事を公開しました。

「読者のため」に書いています、と言いたいところですが、いろいろ難しいので「自分のため」と思って書くのも悪くなさそうですよ、という話を書いたつもりです。良かったら読んでみてください。

今回は、次世代 Web カンファレンス 2023 Technical Writing セッション (Togetter) では話し足りなかったことの一つ「テクニカルライターの存在意義」について補足しておこうという記事です。

もしまだ聞いていただいていない方は、こちらからどうぞ！

はじめに

まずは、「テクニカルライターがプロダクトやチームに貢献できること」というタイトルのこの記事を読むとどんなことがわかるかという点について認識を合わせておきましょう。時間をかけて読んでみたら期待はずれの記事だった、、、みたいなことを避けるためです。

この記事では、テクニカルライターができることを通して、以下の 2 つのことを成そうとしています。

テクニカルライターの採用を検討している方に向けて、テクニカルライターができることを説明しようとしています。テクニカルライターは「わかりやすい日本語を書くことが得意な人」ではありますが、それだけではありません。テクニカルライターを採用すると、どんなタスクをお願いできそうなのか、自社のプロダクトやチームにどんなメリットがあるのかをできるだけ明確に想像してもらうことを目指しています。
テクニカルライターとして働くことに興味を持っている方に、テクニカルライターの仕事が「わかりやすい日本語を書く」だけではないことを理解していただこうとしています。とはいえ、ここに書かれたすべてのことができないと「テクニカルライター」と名乗れないわけではありません。私ができないことも書いてありますｗ　気軽にテクニカルライターを名乗って、プロダクトやチームに貢献していきましょう！

もし、すでにテクニカルライターとして働いている方がこの記事を読んで「こんなこともできるよ～」というような気付きがありましたら、ぜひ別の記事で書いていただいたり、この記事へのコメントでお知らせください。お知らせいただいた内容については、ガンガン追記していこうと思います。別の記事を書いていただければ、リンクさせていただきます！

さて、ここまで読んでみていかがでしょうか。「私の期待する記事ではないな…」と思われる方もいらっしゃるかもしれません。その場合は、今日はここで読み終えると良いでしょう。テクニカルライターを探してみようかな、と思ったときに改めて読んでいただけると幸いです。

この記事での「テクニカルライター」とは

次世代 Web カンファレンス 2023 の Technical Writing セッションでも話題になったとおり、テクニカルライターという仕事は、UX ライター、API ライター、プロダクトライター、などなど、様々な名前で呼ばれています。これは、企業によってテクニカルライターに期待するタスクが違うことによるものだと理解しています。つまり各職種に上下関係はなく、たとえば、テクニカルライターが成長すると UX ライターになるとか、逆に UX ライターが成長するとテクニカルライターになる、といった関係は存在しません。ひょっとしたら採用時の名前が違っていても、実際に話を聞いてみると同じタスクを期待されている、ということもあるかもしれません。

この記事では、ドキュメントを書いたり、UI や UX を考えたりする職種を、(歯がゆい思いをする方がいることも承知のうえで、説明をカンタンにするために、泣く泣く)「テクニカルライター」と書いています。テクニカルライター的人材を求めている採用担当の皆さまは、自社の実情/要求にあわせてテクニカルライターに期待するタスクを明確にし、テクニカルライターとして働きたい方と、できること/できないことをすり合わせることを強くおすすめします。

この記事で狙うこと

大事なことなので、表現を変えて書いておきます。この記事では、「テクニカルライター」が担当できそうなタスクを説明しようとしています。その結果、「あと少しドキュメントが良くなれば、サービスを正しく使ってもらえると思うのに / 問い合わせが減ると思うのに」というような悩みを抱えている企業の皆さま (特にエンジニアチームやサポートチーム) が、期待通りのテクニカルライターを採用できる世界を作ることを目指します。

テクニカルライターをひと息で乱暴に説明すると「わかりやすい日本語を書くことが得意な人」です。ただ、いままでテクニカルライターがいなかった組織に、初めてのテクニカルライターを採用する動機として「わかりやすい日本語を書くことが得意な人を採用したい。」というだけでは、チームメンバーから賛同を得るのは難しそうな気がします。日本人が多く働く会社では、みんな日本語は書けるので特に難易度があがると予想しています。

そのような状況を指をくわえてみているだけでは、テクニカルライターの求人 (私たち目線ではテクニカルライター仲間) が増えるのはなかなか難しい、という感触を私は持っていまして、それをなんとか改善したいという思いもあります。

などなど、いろいろ書きたいことは出てくるのですが、なかなかまとまらないので、前説はこのあたりにして、お待たせしました。本編の始まりです！

テクニカルライターができること

上にも少し書きましたが、すでにテクニカルライターとして働いている私たちとしては、テクニカルライターができることは日本語を書く「だけ」ではないぞ、という強い思いがあります。そこで、テクニカルライターができることを整理してみよう、と思い立った次第ですが、すべてのテクニカルライターができることを、正しく漏れなく書くことは難しいです。

もし、すでにテクニカルライターとして働いている方に、「この記事では書いてないけど、こんなこともできるよ～」というようなことを教えていただければ、追記していきたいという気持ちもありますので、どしどし情報をお寄せください。この記事は、常に書きかけです。

ちなみに随所に「日本語」とでてきますが、ほかの言語を扱える方も少なくありません。適宜、必要な言語に読み替えてください。

わかりやすい日本語を書く (ために時間を使える)

テクニカルライターは、わかりやすい日本語を書くために時間を使えます。テクニカルライターが書いた文章を、エンジニアやサポートチームのメンバーに確認してもらって、もし違和感があれば、丁寧に違和感の原因を確認し、より違和感が少ない日本語を検討できます。

このように書くと、想像の範囲を超えないと思いますので、ここではテクニカルライターが何をしているのか、もう少し掘り下げてみましょう。文章を書くだけではないその周辺の作業がわかると、テクニカルライターの輪郭がくっきりするかもしれません。

執筆前の準備に時間をかける

テクニカルライターの仕事は執筆する前から始まります。執筆前の準備として、新機能を説明する文章を書くために、新機能に関連する前提知識や周辺知識を収集します。

ここでは、(自社、他社問わず) 似たようなサービスを理解したり、似たような既存機能を理解したり、といった作業をイメージしてください。もう少し具体的に書くと、似たようなサービスのユーザーがどういうつもりで既存のサービス/機能を利用しているのかを理解するために、実際に自分で体験したり、そういったサービス/機能が世の中でどのように捉えられているか、どのように説明されているかを調べたりします。

あらかじめ既存のモノを理解したり体験したりすることで、ユーザーがサービスに期待することや、サービスを利用するときの前提などについて、できる限り理解します。

既存のモノの理解はギャップの発見に繋がる

既存のモノを理解したうえで新機能を理解することで、ユーザーが暗に期待していることと新機能のギャップに気がつけるようになります。ギャップに気がつくことは、文章の適切な書き出しを決めたり、適度な注意文を書いたりするためにとても大切です。ちなみに、ギャップは、優れた点になることもありますし、劣った点になることもあります。

優れた点であれば強くアピールしたいと考えますし、劣った点であれば丁寧に注意事項として書いておきたいと考えます。

たとえば、既存の類似サービスがスマホで操作できるのであれば、ユーザーはスマホのブラウザで操作できることを期待すると考えられます。一方で、自社サービスが PC で操作することを前提にしているなら、「PC」を強調することが必要かも？と気がつける、といった具合です。

このように、新機能のコンセプトをより正しく理解したり、ユーザーの考えかたを理解したりするための準備に時間を使えることは、テクニカルライターができることのひとつと言えるでしょう。

さらに、テクニカルライターとして自社のさまざまなサービスのドキュメントを書き続けていくと、サービス間の関係が見えてきたり、サービスごとのユーザーに関する知識が増えたりすることで、より適切にギャップに気が付けるようになります。知識が増えれば増えるだけ、より多くのユーザーに伝わりやすい、大局的でわかりやすい説明が書けるようになるでしょう。

エンジニアが、担当する部分のドキュメントを書くことでは気が付くことが難しいギャップも、さまざまなサービスを担当するテクニカルライターなら気が付けるかもしれません。

執筆

既存のモノをできる限り理解したうえで、自社の新機能の仕様書などの資料を読んだり、実際に体験してみたりしながら、ドキュメントを執筆します。ここではエンジニアやプロダクトマネージャー、プロダクトオーナーが準備してくれたモノを使って理解しながらドキュメントを書くタスクをイメージしています。

どんな資料があればドキュメントを書けるか

どのような資料があればいいですか？とよく聞かれますので、私の経験を紹介します。これまでに新機能を理解するために使った資料の概要です。これ以外のパターンもあったような気がしますが、仔細は忘れてしまいましたｗ　結論としては「何でも大丈夫なのでご相談ください」です。

エンジニアが開発のために作った仕様書を読む。

仕様書の内容については本当に千差万別ですが、ここで重要なのは「エンジニア (またはエンジニアに近しい人) が用意したもの」を読める、ということです。具体的には、分厚い画面遷移図と機能仕様書を読んだこともありますし、API 仕様を読んだこともありますし、こんなことができるようになる予定ですというざっくりした資料を読んでドキュメントを書き始めたこともあります。
(エンジニアじゃない誰かが) お客様に概要を説明するために作ったプレゼン資料を読む。

たとえば、主な画面とか特徴的な機能の説明が断片的に掲載されているプレゼン資料をイメージしてください。ある画面から別の画面にどのように遷移するかは書かれていなくても、ドキュメントを書き始められます。お客様がわかってテクニカルライターがわからないということはありません。
プロダクトオーナーが、新機能を開発するために必要な背景や、ユーザーができるべきこと (ユーザーストーリー) を書いた資料を読む。

画面の説明や、新機能が追加される場所も書かれていない資料をイメージしてください。ユーザーストーリーから、あの画面のこのあたりに機能が増えるんだろうな、というアタリを付けてドキュメントを書き始められます。これらの資料から書き始めるドキュメントは、このあとに説明する「網羅的に書く」を意識して書いたドキュメントをイメージしてもらって大丈夫です。

以上のように、新機能のことがわかるものであれば、どんなものでもドキュメントを書き始められますが、それだけで正しいドキュメントが書けるかというと話は別です。テクニカルライターが疑問に思ったことや曖昧なことは質問させてもらうことになります。一つひとつ漏れなく対応をお願いします。また、リリースするまでには、開発された新機能とドキュメントの説明に齟齬が無いか、チーム全員で丁寧に確認する必要があります。初めに提供される資料が完成品に近ければ近いだけ、テクニカルライターが完成品に近いドキュメントを書けると思ってもらえると嬉しいです。

何を気にして書いているのか

テクニカルライターが何を気にして書いているのか、というのも説明したいところですが、実はこれは「ドキュメントを誰のために書いていますか」で丁寧に触れたつもりです。あの記事では、以下の 3 つの帽子をかぶりながら自分のためにドキュメントを書く方法があるということを書きました。

ユーザー (主な読者) の代表のつもりの自分の帽子をかぶって、「標準的な手順」と、その手順を実行しているときに「びっくりすること (＝操作しているときに期待を裏切られること)」や「取り返しがつかないこと」をできるだけ書きます。
エンジニアの代わりのつもりの自分の帽子をかぶって、「新機能を利用するうえで、必要なことを網羅的に書けているか」「仕様を正確に説明できているか」を考えながら書きます。
3 か月後の自分の帽子をかぶって、「一文一文がわかりやすいか」「説明の流れはわかりやすいか」という観点で文章を書きます。

このように複数の帽子をかぶりながらドキュメントを書けるのはテクニカルライターの強みでしょう。

網羅的に書くのは訓練が必要です

この記事では特に改めてエンジニアの代わりのつもりの自分の帽子をかぶっているときの「網羅的に書けているか」という点について追記しておこうと思います。

この「網羅的に書く」は意外と難しくて、慣れが必要です。訓練が必要と言ってもいいかもしれません。視点を変えながら、同じページの説明を何度も読み直したり、何度も操作したりすることになります。書くことに使える時間が長いテクニカルライターなら、根気よく「網羅的に書く」ことができると思います。

ここで「網羅的に書く」の具体例を紹介しましょう。これで「ちょっと大変そうだな…テクニカルライターにお願いしたいな…」と思ってもらえると、テクニカルライターの存在意義のひとつとして認められるかなという期待があります。

「新機能のすべての手順を書く」「すべての注意事項を書く」

これは基本的なことです。想像通りで、できそうに見えるのではないでしょうか。
「ほかの機能に影響を受けるケースの説明を書く」

機能によっては、ほかの機能の設定に影響を受けて動作が変わることもあるでしょう。そのような場合も「網羅的に書く」必要があります。オプションを設定していたら標準の手順通りに操作できなかった…となれば問い合わせがくるに違いありません。これを「網羅的に書く」のは、さまざまな機能がどのように関連してくるのか理解する必要があるのでちょっと大変です。根気よく知識を増やしていく必要があります。
そのほか、以下のような場合も「網羅的に書く」必要があります。
- 「オプションサービスの契約の有無に影響を受けて動作が変わる場合の説明を書く」
- 「初めて利用するときと 2 回目に利用するときで動作が違う場合の説明を書く」
- 「エラーが出るケースで、特別な注意事項や復帰手順の説明を書く」

ここに書いたものは「網羅的に書く」の例です。そのほかにもさまざまなケースがあるでしょう。ユーザーが普通に操作してたどり着きそうなケースについては、できる限り「網羅的に書く」必要があります。

ということで、「網羅的に書く」ことは思いのほか大変そうだぞ…、という感触を持っていただけるとうれしいです。

ちなみに私の場合、たとえば「ほかの機能に影響を受けるケース」を網羅的に書くときは、想像だけではなく実際に設定を変更したうえで、新機能が「設定を変更したユーザーが想像するような動作」をするかどうかを想像しながら、原稿を書きます。そのように想像することで初めて「適度な注意文」や「適度な手順分岐」などが書けるような気がしています。

「網羅的に書く」作業の副産物として、開発時に考慮が漏れていたエッジケースをテクニカルライターが見つけることもあります。

公開

不本意ながら、さまざまな制約で最高のドキュメントにはならないことがあります。それでも、できる限りわかりやすい日本語で落としどころを見つけて公開するという勇気や、関係者との調整能力も期待してください。最高の文章を求め続けて、なかなか公開できず、サービスがリリースできなかったり、サービスはリリースできたもののユーザーに情報が届かないのは、本末転倒とわかって仕事をしてくれるはずです。

ちなみに、上の方でも書きましたが、ドキュメントの正しさについては、テクニカルライターだけに任せるのではなく、チーム全員で確認していきたいところです。

プロダクトへのフィードバック

テクニカルライターができることはまだあります。それは、プロダクトへのフィードバックです。

mochikoAsTech さんが紹介してくださった「プロパティ名を相談したらテクニカルライターが集まってきていろいろアイディアを出して去って行ったエピソード」も、プロダクトへのフィードバックの一つの形だと思います。あのエピソードは、開発時に悩んでいるから相談する、というものでした。また違うタイミングのフィードバックも考えられます。たとえば、開発がひと段落したあとにテクニカルライターが実際に触った結果のフィードバックです。

エンジニアとテクニカルライターの関係

新機能の奥深くまで理解したエンジニアが作ったプロダクトに対して、奥深くまで理解していないテクニカルライターがフィードバックできるのか？という疑問があるかもしれません。

そこで、フィードバックの話をする前にエンジニアとテクニカルライターの守備範囲の違いについて少し書かせてください。これは私の勝手な想像が含まれているので、もし全然違う、ということがあったらこっそり教えてください。

私はエンジニアとテクニカルライターは以下の図のような関係にあると思っています。新機能が海の上に浮いているイメージです。

この図は、以下の 3 つを図示しています。

ユーザーが理解する範囲。氷山の一角のようなイメージで水面より上に出ている部分です。テクニカルライターがドキュメントで説明する範囲とも言えます。
テクニカルライターが理解する範囲。赤枠の部分です。
エンジニアが理解する範囲。黄色、緑、オレンジの図形で示しています。3 人で分担して 1 つの新機能を開発していることを示していると思ってください。ひょっとしたら、ほかのエンジニアの担当部分も深く理解していることが期待されるかもしれません。

テクニカルライターが理解する範囲は、一人ひとりのエンジニアが理解して開発している範囲と比べるととても浅いです。エンジニアと比べれば極めて表面的とも言えます。

一方で、ユーザーが理解する範囲と比べると、テクニカルライターが理解する範囲は少し深くなります。ユーザーに説明するために少し深く理解していることをイメージしてください。つまり、ユーザーが新機能を正しく使えるようにするために、ユーザーよりも少し深く理解して説明する、それがテクニカルライターができることという考えかたです。

そう考えると、この図はスッと腹落ちするのではないでしょうか。

ここまでは、縦方向の「深さ」に注目した説明でした。実はこの図で伝えたいことはもう一つあります。それは、横方向の「広さ」です。どのエンジニアと比べても、テクニカルライターが理解する範囲は横方向の広さが広いことが読み取れますね。さらにテクニカルライターが場数を踏んでいけば、新機能だけではなく、そのほかの機能についても「テクニカルライターが理解する範囲」が増えていきます。横方向の「広さ」という点では、エンジニアよりもテクニカルライターに分があることを想像していただけると嬉しいです。(ひょっとしたら賛否両論あるかもしれませんが、恐れずに書いてみました。)

プロダクトの専門家は間違いなくエンジニアです。なにか曖昧なことがあれば、最終的にはエンジニアに調べてもらうほかありません。つまり、そのプロダクトをもっとも深く把握しているのはエンジニアであることに疑いの余地はありません。そしてテクニカライターは、プロダクト全体をユーザーよりも深く、エンジニアよりも広く理解する役割を持っていると考えています。

ここまで、エンジニアとテクニカルライターの関係についての私の考えでした。

テクニカルライターが実際に触って行うフィードバック

そのようなテクニカルライターが、リリース前のプロダクトを、ユーザーの代わりにすべて体験することで、エンジニア一人ひとりが気が付かなかった点をフィードバックできます。もちろん、エンジニアがすでに検討済みであることもありますが、検討できていなかったこともあるかもしれません。

たとえば前準備をしっかりしたテクニカルライターであれば、「今の仕様は、XX の点でユーザーの期待と少しずれているかもしれません。(既存のモノを知っている) ユーザーはこういうインターフェースを期待している可能性があります。」といったフィードバックができるかもしれません。このとき、表面的に少し触って感じた内容をフィードバックするのではなく、すべての機能を触り、漏れなく様々なことを考えて執筆がほぼ終わったタイミングでフィードバックできることが大切です。

言い換えると、新機能をすべてさわってすべてをうまく説明する方法を検討したうえでのフィードバックです。テクニカルライターの直感だけで (ユーザーのふりをして) 違和感があったところをむやみに伝えるフィードバックではありません。客観的に証拠を集めてフィードバックするように心がけることで、プロダクトにとっても価値があるフィードバックになるのではないでしょうか。

ほかにも「正しくエラーが出る手順」も確認してエラーメッセージの内容 (「エラー」だけではユーザーはつらいでしょう) を確認したり、「想定外の問題が発生しそうな手順」も確認して動作を確認したりします。その結果、必要に応じてドキュメントで補足しますが、場合によってはプロダクトにフィードバックします。

このようにテクニカルライターが執筆しながら実際のサービスをリリース前に試すことで、プロダクトにいい影響を与えることも期待できます。

ただ、このフィードバックがリリース予定の数日前、のようにぎりぎりになってしまうとお互いに辛いので、スケジュール的にフィードバックする余裕があるといいのですが、難しいこともありますね。ひょっとしたらプロジェクトの開始時点からチームの輪に入れてもらってもいいかもしれません。相談してみてください。

UI 文言や画面遷移も考える

「製品の魅力や意図が伝わるような UI」になっているか、「もっといい UX にできないか」を考えることもテクニカルライターのタスクの一つに数えられます。UX ライターと呼ばれるときは、このタスクに大きな期待していることの表れかもしれません。

正直に書くと、私はこのあたりはあまり得意ではなく経験も多くないので、ここで細かく書くことができません。。とはいえ、私の少ない経験でも、ドキュメントで説明したい内容 (＝サービスの世界観) を、UI のラベルや配置、画面遷移によって、正しく伝えられていないのでは…と思うときにフィードバックすることはあります。

ツールを導入したり開発したり CMS のメンテナンスをしたりする

これは Technical Writing セッションでは一切話題に上がりませんでしたがｗ

エンジニアのバックグラウンドをもったテクニカルライターの場合、執筆を便利にするようなツールを導入したり開発したりすることが得意なことがあります。私は正確にはエンジニアのバックグラウンドはありませんが、テクニカルライターの中では得意な方だと思っています。本当にエンジニアバックグラウンドを持っている方にはかないませんが。

簡単なところで言うと、textlint を導入したり、画像を作成する工程を整備したり、といったところから、スクリプトを書いて業務を非常に簡単にすることもありますし、(弊社の場合は) Hugo の Shortcode を書いて、markdown の記法を拡張したりすることもできます。こういったことをエンジニアに依頼するのではなく、テクニカルライター自身が対応することで、かゆいところまで手が届くようなツールを導入できたり、完璧さを求めすぎない適度なツールができたりします。

直近での開発経験でいうと、最近ブームの ChatGPT の話があります。ChatGPT に知識 (参考資料) を与える RAG (Retrieval Augmented Generation) を利用した Q&A ボットの開発に強く関わらせてもらっています。LangChain というパッケージを使ったボットを開発していて、いまは ver.3 が社内で動いています。テクニカルライターがドキュメントで説明されている内容を把握したうえで、Q&A ボットを開発するので、「ボットが回答できる質問」と「ボットが回答できない質問」を、いい精度で判断できるところが強みと考えています。たとえば、「ボットが回答できる質問」のはずなのにボットが回答できないということは、何か伸びしろがあるはず、と判断できます。また「ドキュメントを修正するべき」か「ボットのアルゴリズムを修正するべき」かを正しく検討できるのも、ドキュメントをすべて把握しているテクニカルライターならではの強みと言えるかもしれません。

テクニカルライティング講座を開催する

それから、テクニカルライターが日常的に気にしていることを社内でシェアすることもできます。言うなれば「テクニカルライティング講座」の講師が得意なテクニカルライターも少なくありません。私も好きで、よく講座を開いていました。説明する内容を考えるのが好きなのですよね。

講座の具体例として、かの有名な Cybozu のテクニカルライター仲田さんが公開してくださっている「テクニカルライティングの基本 2023年版」のような内容をイメージするといいかもしれません。社内のテクニカルライターが講座を開催する場合は、自社の事例を取り上げてテクニカルライティング講座を開催してくれるかもしれませんね。講座を通して、社員が書くドキュメントが読みやすくなり、正確に情報伝達ができるようになることが期待できるかもしれません。

まとめ

ということで、「テクニカルライターがプロダクトやチームに貢献できること」というタイトルで、テクニカルライター (この記事では、テクニカルライター、UX ライター、API ライター、プロダクトライターなどの総称) ができることを書いてみました。いい棚卸しになった気がしますが、期待通りの内容だったでしょうか。感想を聞かせてもらえると嬉しいです。

新卒のころからテクニカルライターという人 (私がそうですがｗ) はまだ珍しいようで、つまりテクニカルライターになる前の職業がバラエティに富んでいるのも現時点ではテクニカルライターの面白いところだと思います。

テクニカルライターを採用するとき/応募するときは、「テクニカルライター」という職名で判断するのではなく、「日本語を丁寧に書く」ことに加えて、何を得意としているのか、何が得意じゃないのか、何を期待しているのか、などをしっかり確認できると、企業もテクニカルライターもお互いに幸せになれるのではないでしょうか。

プロダクトやチームに貢献できるテクニカルライターと出会えるように/テクニカルライターになれるように、みんなで知識を共有しながら (ブログなどを書きながら) テクニカルライター業界を盛り上げていきましょう！