aptpod Tech Blog

株式会社アプトポッドのテクノロジーブログです

ドキュメントができるまでの社内コミュニケーション

aptpod Advent Calendar 2022も、22日目になりました。本日は、ドキュメント担当の篠崎がお届けします。

私は、社内で1人だけの「ドキュメント担当」*1として、社外に公開するマニュアルや技術ドキュメントの制作を行っています。

ドキュメントは新製品・新機能のリリースに合わせて制作しますので、私は、新製品・新機能の開発担当者*2と常にコミュニケーションをとりながらリリースまでの作業を進めています。

そこで、この記事では、テクニカルコミュニケーターとしてのドキュメント担当が、製品開発担当者とどのようにコミュニケーションをとりながら仕事を進めているか、書いてみたいと思います。*3

(なお、ここでご紹介するやり方は、弊社内で「このようなドキュメントだったらこのようなやり方をする」といういくつかのパターンのうちの1つです。すべてのドキュメントを同じ方法で制作しているわけではありません。)

この記事で例にするドキュメント

この記事では実際の例として、最近公開した「intdash Edge Agent 2 デベロッパーガイド」(PDF版およびHTML版)の制作を振り返りながら書いてみたいと思います。

「intdash Edge Agent 2 デベロッパーガイド」は、弊社ソフトウェア製品である「intdash Edge Agent 2」を活用いただくための、開発者向けガイドです。 本製品をLinux PCにインストールすると、そのPCはデータ伝送プラットフォームintdashのクライアント(エッジ)として動作するようになります。

本製品は、従来からある同等の製品「intdash Edge Agent(末尾に2が付かない)」を使いやすくリニューアルしたものであるため、デベロッパーガイドも完全にリニューアルし、一から作ることにしました。

なお、ドキュメント制作に使用しているツールはSphinxです。また、原稿データは社内GitLabリポジトリで管理しています。

制作の体制と流れ

このドキュメントの制作には、主に以下の3名が携わりました。

  • ライター1名(私)
  • 当該製品の開発担当者1名(ただし、これ以外の開発メンバーにも要所要所で助けてもらっています)
  • プロダクト開発責任者(かつライターの上司でもある)

また、スケジュールは、開発日程との関係、また、ライターの他の作業との関係から、以下のようになりました。

  • 7月中旬:ドキュメントのキックオフミーティング
  • 8月上旬:開発担当者の原案をもとにライターが作業開始
  • 8月下旬:原案を整理し、ライターにて新しい目次を提案、OKをもらう
  • 9月下旬:第1回レビュー(開発担当者およびプロダクト開発責任者がレビューする。以降、レビューを重ね、その都度修正する。)
  • 12月上旬:第5回(最終)レビュー
  • 12月中旬:公開

ライターは7月から12月までずっとこの作業をしているわけではなく、他のドキュメントの制作も同時に進めています。 レビュー日程は作業の進捗に応じてその都度設定する形としました。

ドキュメントのキックオフミーティング

まず、7月中旬に今回のドキュメント制作に関するキックオフミーティングを行いました。 ここでは、開発担当者から「このようなドキュメントをつくってほしい」という要望をもらい、以下のことについて説明を受けました。

  • intdash Edge Agent 2とは何か(特に、既存製品との違い、ユーザー像)
  • 開発スケジュールとドキュメント制作スケジュール
  • ユーザーに説明しなければならないことの一覧
  • 社内にある関連資料(設計関連のドキュメント、インストール用パッケージなど)のありか

今回の場合、このキックオフミーティングを受けて、上記の「ユーザーに説明しなければならないこと」は、開発担当者にて原案を書いてもらうよう依頼しました。

「誰が執筆工程を担当するか」については以下のように役割分担をしているのですが*4、今回は、上から2番目の「開発者向け製品マニュアル」の方法を採用したということになります。

開発担当者とライターの役割分担

目次を作成して提案

8月上旬、予定通り、十分な情報がしっかりとつまった原案を開発担当者からもらいました。

原案を読み込み、以下のように大きく3部に分けて整理することにしました。

  • まず動かしてみるためのチュートリアル
  • 目的に応じてやり方を参照するためのガイド
  • 網羅的リファレンス(ここに、設定レシピ集も入れる)

これは、これまでの別ドキュメントでの反省をふまえ、また、Divio Technologies社のThe Documentation Systemなどのベストプラクティスを参考にしたものです。

目次案

新しい目次について開発担当者やプロダクト開発責任者から承認を得られたら、実際にリライトおよび執筆に入っていきます。

開発担当者によるレビュー

8月下旬以降、説明対象のソフトウェアを実際に操作し、調査や実験をしながら、文章を書いていきます。今回は開発担当者が書いた原案があるので、原案を利用できるところは利用しながらリライト、原案がない部分は自分で一から書きます。

ある程度形になったら、開発担当者やプロダクト開発責任者にレビューしてもらいます。 このレビューは、技術的側面から正しい記述になっているかを確認してもらうのが主な目的です。

レビュー結果を書き込んでもらう方法としては以下の2つを使いました。

  • 機能追加等により、まとまった修正が必要な時は社内GitLab上のマージリクエスト
  • 細かい指摘はGoogleドライブ上のPDFにコメント

テキストが主体のドキュメントであれば、細かい指摘もマージリクエストでやり取りをしますが、今回のドキュメントは図や表がたくさんあることから、PDFをGoogleドライブで共有し、そこにコメントをつけてもらう方法を使用しました。 基本的に、レビューコメントを付けてくれるのは開発担当者とプロダクト開発責任者ですが、必要に応じて関連する人がメンションされて呼び出され、議論に加わってくれるという形で進みました。

PDFでのレビュー(開発者がメンションされて呼ばれてきたところ)

ライターはどこまで自分で悩むべきか

説明を書いていると、たびたび仕様についての疑問が生じるのですが、どのくらい悩んでから開発担当者に質問すべきか迷います。 私はだいたい、「もう行き詰まった」と思うところまで頑張って一人で悩むようにしています。同時に、「行き詰まった」と感じるところまでできるだけ早く行くように心がけています。 これは、社内のライターとして、自分で答えを探すために必要な材料が十分に与えられているためです。

今回の場合は、手元のDocker環境で、説明対象のソフトウェアを動作させ、実験をすることができました。 実験用のintdashサーバーも自由に使えるため、設定を変えて好きなだけデータの送受信を試してみることができます。 また、社内WikiやGoogleドライブに保存されている設計段階の多くの資料も見ることができます。 (逆に言うと、自分で実験できない場合や資料へのアクセスがない場合は、早く聞くしかないということになります。)

実験環境や社内資料など、情報へのアクセスが十分にあるところでしっかり一人で悩んでおくことは、無駄にはなりません。

  • 一人で考えて行き詰まったとしても、開発担当者に質問するときには、最終的に行き詰まった地点を示し、なぜその道筋をたどったのかを添えて質問すると、開発担当者は返答をしやすくなる(はず)。
  • 自分が行き詰まったということは、これからドキュメントを読むユーザーも同様に行き詰まる可能性が高い。その道筋を自分で体験していれば、それを避けるように説明ができる。

例を挙げてみます。以下は、なんらかの設定項目(ここでは設定項目Xとします)の機能について説明を書こうとして疑問が生じたケースです。ここでは、「このまま考えたら矛盾することが分かった」というのが「行き詰まり」であり、それをもとに質問しました:

設定項目Xの機能はAということであると考えました。 しかし、他に設定項目Yがあるので、Xの機能がAとするとXとYの設定が矛盾することになります。 もしかして、Xの機能はBでしょうか。

開発担当者の返答は、だいたい以下のいずれかになります:

(例1)Xの機能はAという理解で正しいです。Yの機能は特別なケースのための設定で、...

Aという理解で正しかったということで安心です。でも、悩んだ甲斐がありました。Xについて悩むことでXについて正確に理解しているので、「Xとは異なるY」をどのように説明すればよいか、見えてくるからです。

あるいは以下のような返答もありえます。

(例2)そうです、Xの機能は実はBなんです。ちょっと分かりにくいかもしれませんね、そもそもXがなぜ存在するかというと....

うーむ、Xの機能はAだと予想したのは間違いだったようです。でも、悩んだ甲斐がありました。自分がこのように予想したということは、ユーザーもそのように予想する可能性が高いからです。なぜ自分がそう予想したかを念頭に入れて、Xの「そもそも」のところを説明する必要がありそうです。それにより、Xの位置づけがスムーズに説明できるとよいです。

さらには、以下のような返答もあるかもしれません。

(例3)いいえ、Xの機能は、AでもBでもなく、Cです。どういうことかというと...

予想していなかった第3の答えでした。でも、悩んだ甲斐がありました。これまでAとBを念頭に置いて悩んできたわけですが、ここでも、「Aはでなく、Bでもない」ということがCを理解するための支えになります。

例2や例3のように理解や予想がしにくい機能は、説明を書くと長く複雑なものになってしまうことがあります。そんなとき、場合によっては、「こんなに説明が難しくなってしまうということは、この仕様は見直したほうがよいかも」「設定項目の名前を変えたほうがよいかも」という話になり、ドキュメント化がきっかけで仕様の見直しにまで進むことがあります。 こういうことができるのは、製品開発とドキュメントの制作が社内で緊密に連携しながら進んでいるからこそだと思います。

なかなか複雑なやりとりになってきました。PDFやマージリクエスト上のコメント上で会話を続けて解決すればよいですが、例2や例3のようなケースでは、詳細なコミュニケーションが必要になります。 そんなときは、ライターが主催して、疑問点を解決するためのミーティングをします。

疑問点解決のためのミーティング

疑問点解決のためのミーティングでは、ライターは聞きたいこと(時によって1個から20個ぐらい)を書いた資料を用意しておいて、ひとつひとつ開発担当者に聞きながら解決していきます。

今回のドキュメントでは、開発担当者と7~8回のミーティング(各回1時間ぐらい)をおこなったと思います。 通常、もっと小さなドキュメントや、既存ドキュメントの改版の場合はこんなに多くのミーティングはおこないませんが、前述のとおり、今回は一から新しく制作したため、頻繁におこないました。 *5

ちなみに、普段私はリモートワークをしているのですが、たまたまオフィスに出社した日に開発担当者も出社していて、「せっかくなのでマニュアルの疑問点を解決しましょう」ということになって、オフィスの片隅でミーティングをおこなったこともありました。 対面でミーティングをすると、マウスポインターではなく自分の指を使って「ここの説明が...」と指し示したり、手元の紙に簡単な絵を描いたりしながら話ができ、やはりはかどります。

以上のような工程を経て、最終レビューを通過したら、公開することができます。

ひと段落、ではありますが、ここから先も、「このことが書かれていない」「こう書いてほしい」といった要望をもらうことになると思います。終わりはありません。

おわりに

どんなふうにドキュメントを作っているのか、今回は社内での開発者とのコミュニケーションに焦点をあてて、一端をご紹介してみました。

ドキュメントを作るテクニカルライターは、ドキュメントをただ「きれいに」してくれる人というわけではなくて*6、もっといろんなところで役に立つことができるはず、と思っています。

テクニカルライティングはテクニカルコミュニケーションの一分野であり、今回は、社外の方々に対して「コミュニケーション」をするためのドキュメントを作ったわけですが、そのために社内でも、いわば仕込みの段階で、開発担当者と「テクニカルなコミュニケーション」を繰り返しています。

このような社内コミュニケーションの成果が、例えば上記のような「仕様自体を見直そう」という動きになったり、「ここのところは詳しく説明しよう」という話になったりして、社外にお届けする製品およびドキュメントの改善につながります。そのようなことをめざして、働いています。

*1:弊社のドキュメント担当の仕事については、以前 「ひとりドキュメント担当」の仕事 でもご紹介しました。

*2:テクニカルライティング業界だと、ドキュメント制作におけるこの立ち位置はSME (Subject Matter Expert)と呼ばれます。

*3:実は、「私と同じようにドキュメントを内製されている方はどうされているのかな、どのようなやり方がよいのかな」といつも気になっています。「知りたいことがあるときは、まず自分のことを書いてみよう」と思ったのでした。

*4:この表は以前LINE Technical Writing Meetup vol. 11で発表させていただいたときのスライドから流用しました。

*5:弊社内のコミュニケーションガイドラインでは、「翌営業日以降なら事前確認なしに空いているところにミーティングを入れてもよい」となっているので、「うーん、これは聞かないといけないな」となったら、翌日のGoogleカレンダーにポンとミーティングスケジュールを入れます。

*6:テクニカルライターはドキュメントをきれいにしてくれるだけの人と思われてしまう件についてはこちらに興味深い記事があります。