관련링크

こんにちは、WhaTap Labsのテクニカルライターである、Sunnyです。今日は良い技術文書が必要な理由について話してみましょう。

そしてWhaTapは良い技術文書を作るためにどんな努力をしているのかについて申し上げます。

良い技術文書が必要な3つの理由

第一、文書は企業のレベルを示しています。

技術文書をいくらよく書いておいても、とにかく顧客は見ないと思う人がいるかもしれません。文書が異なるといってもどれだけ異なるだろうと思われるかもしれません。しかし、明らかに異なります。うまく書かれた文書とそうではない文書には違いがあります。企業の公式文書に誤字、スペル、浮き書きが守られていない場合があります。顧客がそのような公式文書を見たら、どう思うのでしょう？ 「この企業は基本的な語法すら守らないんですけど、果たしてサービスはちゃんとしてもらえるかな？」と思われるかもしれません。良い企業は細部まで慎重に取り組むべきです。それだけで信頼性が維持できます。

第二、うまく書かれた文書は企業と顧客の時間を節約します。

製品を使って困っていることがあるとしましょう。最も簡単な方法は、顧客センターに連絡して質問に対する答えを見つけることです。問題は、まとめられた文書がない場合、または文書に最新のものが正しく更新されていない場合です。カスタマーサービス担当者は、毎回同じ質問が出るたびに直接回答する必要があります。まとめられた文書がないため、担当者を探して確認するのに時間がかかります。結局悪循環が繰り返されるわけです。

お客様の立場でも大変なのは同じです。時には答えを待つよりも関連文書を直接探す方がはるかに高速です。しかし、いくら探しても解決策が出てこなかったらどうでしょうか？ 読んでもどういうことなのか分からないと慌ててしまうのでしょう。顧客センターに連絡してもすぐに答えてもらえないと腹立つでしょう？ お客様のエクスペリエンスに悪影響を及ぼします。

最後に、文書は企業の資産です。

もちろん、良い製品を開発することが重要です。しかし、それに劣らず開発した製品に対する正しい使用方法とプロセスを記録として残すことも欠かせないプロセスです。「開発者に直接尋ねればいいのですが、なぜ必ず文書でまとめなければなりませんか？ 忙しいし面倒です」と思われるかもしれません。

しかし、必要なときはいつでも開発者に直接尋ねなければならない場合は、最終的にはより多くの費用がかかります。さらに、開発者が退社した場合はどうなりますか？ 開発者が個人的な事情があってすぐに連絡ができない場合、またどう対処すべきでしょうか。企業規模が大きくなるほど、記録を文書として残す必要があります。担当者だけに頼ると、緊急事態があるときに仕事が大きくなる可能性があります。

WhaTapの技術文書改編コース

1. 技術文書構造の再構成

文書の詳細メニューを統合しました。

従来はメインページで文書をタップするとサブメニューでサポートホーム、文書、リリースノート、カスタマーサポートが出る仕組みでした。ガイドドキュメントを見るには、ドキュメントメニューをタップしてもう一度ドキュメントをクリックする必要があり、面倒であるという意見がありました。

現在改編された文書構造では、メインページで文書メニューをクリックすると、技術文書ページが新しいウィンドウに表示されます。リリースノートはドキュメントページに含まれています。使用率が低下した既存の統合形式のカスタマーサポートページ(FAQ)は、各関連カテゴリ内に詳細な目次として含めました。たとえば、Javaエージェントのインストールに関するトラブルシューティング方法は、関連メニューであるインストールで確認できます。

どのエージェントをインストールしても、一般的に実行する必要があるプロセスがあります。例えば、会員登録をして、プロジェクト作成後にライセンスを発行することです。これらの必要な手順を各言語のエージェント文書に毎回置くのではなく、始めるというカテゴリに分けました。

2. ユーザビリティテスト後の文書への即時反映

開発者が新機能によって開発されると、テクニカルライターは展開の時点でガイドドキュメントを準備します。(状況によって異なる場合がありますが)DevOpsチームで基本概念の説明を書くと、フロントパートはUIの使い方を書く式です。

この時点で、テクニカルライターは新しい機能を直接テストします。試してみながら、ガイド文書と矛盾する内容はないか、慎重に確認してみてください。例えば、開発中に画面上のメニュー名が変更されたが、ガイド文書には反映されない場合があります。これらの詳細を慎重に確認しながら、ガイド文書を整理するプロセスを経ます。このとき、誤字やスペルも確認します。

それだけでなく、私がユーザーならどんな内容が気になるのか悩んで、ガイドに内容を追加します。最近新しく開発されたログモニタリングという機能があります。ログモニタリングでは、ログ照会パスワードが設定できました。初めて受け取ったガイド草案では、ログ照会パスワードを書く理由、誰が設定できるのか、パスワードを忘れてしまうと、どのように修正できるのかという内容が欠けていました。この欠落は、開発者と確認後のガイドに適用されます。

3. 絶え間ない内部フィードバックの収集

良い文書を作るためには、複数の人が力を合わせなければなりません。テクニカルライター一人ですべてを手に入れるのは難しいです。私が属しているDevOpsチームだけでなく、関連チームのメンバーからのフィードバックを受け取り、文書に即座に反映しています。反映後、技術文書で更新された部分を顧客に直接相手の担当者に共有します。

4. 関連ドキュメントリンクを追加

以前は、Serviceリリース ノートにどのような新機能が追加されたかを一覧表示していました。現在、リリースノートに関連機能に関する説明リンクを置いています。たとえば、2021-10-06に登場したService 1.50.0リリースノートには統合レポート機能が追加されました。リリースノートの内容で統合レポートの単語をクリックすると、ガイドドキュメントに関連する説明がある場所に移動します。このように、ユーザーはリリースノートの新機能が何であるかを見てから、リンクからより詳細な情報を把握できます。

これに加えて、ユーザーが必要な文書を簡単に見つけることができるようにUXを悩んでいます。優れた技術文書は、内容だけでなく、見やすい配置、デザインなどを備えていなければなりません。WhaTabでは、優れた技術文書を作成するために、DevOpsチームのテクニカルライター、エンジニア、フロントパーツ開発者、デザイナーが全力を尽くしています。

技術文書に関してコメントがあれば、いつでもお話しください😉

[email protected]にメールを送ったり、WhaTap Labsのオンラインカスタマーサポートを通じてお話しください。

お客様が良い技術文書でWhaTap製品をより手軽に使用できるように最善を尽くします。