伝えること

Tutorial Advent Calendar 2020　8日目担当 エンジニアの熱田です。

「Robotic Crowdを支える技術」というアドベントカレンダーのテーマですが、ドキュメント（説明書）でうまく機能を伝えることも技術の内という視点で記事を書きました。

きっかけ

エンジニアとして新機能追加などをする際にAPIドキュメント（説明書）を参考にすることがありますが、いろいろなドキュメントを読んでいると、A社のドキュメントはわかりやすいな、反対にB社はいまいち内容が伝わらないな、と感じることがあります。

Robotic Crowd にもドキュメントがあり、私も機能を実装した際には追記していますが、そのときにふと、自分の書いたドキュメントは意味が伝わる内容だっただろうか、と不安になったのが「伝えること」を考えたきっかけです。

この場では過去に出会った不親切な書き方パターンから学び、より良くしていきたいと思った点を書きます。

不親切な書き方パターン

① 主語や目的語が抜けている

「指定の場所に情報を登録する必要があります」

→ 指定の場所はどこ？登録するのは誰？登録する手段は何？

② 情報が不足している

「テキストを出力したいときはこのボタンを押してください」

→ 画像を出力したい場合はどうすればいいの？

③ 説明が抽象的すぎる

「この設定で様々なことが可能になります」

→ 様々なことって具体的にどのようなこと？

伝えるって難しい

伝わる書き方にするためには、主語や目的語をはっきりさせ、具体例を交えつつ情報に不足がないように記述することが必要ということですね。

当たり前のように感じられますが、なかなか難しい。

私も書き方を意識しているつもりですが、他の人から「これってどういうこと？」と確認されて改めて説明不足に気づくことも多々あります。

おわりに

Robotic Crowd は日々新機能が追加されるため、それらの組み合わせ次第で、RPAツールとしてできることが指数関数的に増えていきます。

しかし、いくらプロダクトが優秀であっても、その機能一つ一つの使い方がユーザーに伝わらないようであれば意味がありません。

ドキュメントを読んで「こんな便利な機能があるんだ！」と気づき、「もっとこの業務もRobotic Crowdで自動化させよう！」と楽しんでもらえるようになればいいなと思います。