ユーザードキュメント: 問題の原因と修正方法

ソフトウェアのドキュメントは単なる記事のセットです。 しかし、それらさえもあなたを狂わせる可能性があります。 まず、必要な指示を探すのに長い時間がかかります。 そうすれば、わかりにくい文章も理解できるようになります。 書かれているとおりに実行しても、問題は解決されません。 次の記事を探したり、緊張したり... XNUMX 時間後にはすべてを諦めて立ち去ります。 これが不適切なドキュメントの仕組みです。 何がこのようになるのか、そしてそれを修正する方法 - カットの下をお読みください。

私たちの古いドキュメントには多くの欠点がありました。 上記のシナリオがクライアントに影響を与えないように、私たちはほぼ XNUMX 年かけてこの内容を作り直してきました。 見て、 そのまま и どうやってそうなった.

問題 1: 不明確で不十分に書かれた記事

ドキュメントが理解できない場合、それは何の意味があるのでしょうか? しかし、意図的に理解できない記事を書く人はいません。 これらは、著者が読者や目的について考えず、水を注ぎ、テキストの間違いをチェックしないときに起こります。

• 聴衆。 記事を書く前に、読者の準備レベルについて考える必要があります。 初心者向けの記事では、基本的な手順を省略したり、専門用語の説明を省略したりすべきではないのは当然ですが、専門家のみが必要とする珍しい機能に関する記事では、PHP という言葉の意味を説明する必要があります。
• 目標。 事前に考えておくべきことがもう XNUMX つあります。 著者は明確な目標を設定し、記事の有用な効果を判断し、読者が読んだ後にどうするかを決定する必要があります。 そうしないと説明のための説明になってしまいます。
• 水と虫。 不必要な情報が多く、官僚的で、間違いやタイプミスが認識を妨げます。 たとえ読者が文法のナチスではないとしても、文章の不注意によって読者はうんざりする可能性があります。

上記のヒントを考慮すると、記事がより明確になることは保証されています。 さらに良いものにするために、 技術文書に取り組む際の 50 の質問.

問題 2. 記事はすべての質問に答えていない

ドキュメントが開発に追いついておらず、実際の質問に答えておらず、ドキュメント内の間違いが何年も修正されていない場合は問題です。 これらは作成者の問題ではなく、社内のプロセスの組織化の問題です。

ドキュメントが開発に追いついていない

この機能はすでにリリースされており、マーケティングはそれをカバーする計画を立てていますが、その後、新しい記事や翻訳がまだドキュメントにないことが判明しました。 このため、リリースを延期せざるを得なくなりました。 時間通りにテクニカル ライターにタスクを引き継ぐよう全員にいくらでも依頼できますが、それはうまくいきません。 プロセスが自動化されていない場合、状況は繰り返されます。

YouTrack に変更を加えました。 新機能に関する記事を書くというタスクは、機能のテストが開始されると同時にテクニカル ライターに任されます。 その後、マーケティング部門がプロモーションの準備のためにそれについて学習します。 通知は Mattermost 企業メッセンジャーにも届くため、開発者からのニュースを見逃すことはありません。

ドキュメントにユーザーの要求が反映されていない

私たちはこのように作業することに慣れています。機能が発表され、それについて話し合いました。 オン、オフ、微調整の方法を説明しました。 しかし、クライアントが私たちのソフトウェアを私たちが予期しない方法で使用した場合はどうなるでしょうか? それとも私たちが思いもよらなかったエラーがあるのでしょうか？

ドキュメントが可能な限り完全であることを確認するために、サポート リクエスト、テーマ別フォーラムの質問、検索エンジンのクエリを分析することをお勧めします。 最も人気のあるトピックはテクニカル ライターに転送され、既存の記事を補足したり、新しい記事を執筆したりできます。

ドキュメントが改善されていない

すぐに完璧に行うのは難しく、間違いが生じる可能性もあります。 顧客からのフィードバックを期待することはできますが、誤字、不正確、理解できない、または見つからない記事をすべて報告してくれる可能性は低いです。 クライアントだけでなく、従業員もドキュメントを読んでいます。つまり、同じエラーに遭遇していることになります。 これは使える！ 問題を報告しやすい環境を作り出す必要があるだけです。

社内ポータルにグループがあり、従業員がドキュメントに関するコメント、提案、アイデアを残すことができます。 サポートには記事が必要ですが、存在しませんか? テスターは不正確さに気づきましたか? パートナーは開発マネージャーにエラーについて苦情を申し立てましたか? 全員がこのグループにいます！ テクニカル ライターは、いくつかのものをすぐに修正し、いくつかのものを YouTrack に転送し、他の人に考える時間を与えます。 話題が消えないように、グループの存在とフィードバックの重要性を時々思い出させます。

問題 3. 適切な記事を見つけるのに時間がかかる。

見つからない記事は、見つからない記事と同じです。 優れたドキュメントのモットーは、「検索しやすく、見つけやすい」である必要があります。 これを達成するにはどうすればよいでしょうか?

構成を整理し、トピックを選択する原則を決定する。 読者に「この記事はどこにあるんだろう？」と思われないように、構成はできるだけわかりやすくする必要があります。 要約すると、インターフェイスからのアプローチとタスクからのアプローチの XNUMX つがあります。

1. インターフェースから。 コンテンツはパネル セクションと重複します。 これは、古い ISPsystem ドキュメントの場合でした。
2. タスクから。 記事とセクションのタイトルはユーザーのタスクを反映しています。 タイトルには、ほとんどの場合、動詞と「ハウツー」の質問に対する答えが含まれています。 現在、この形式に移行しています。

どのようなアプローチを選択する場合でも、トピックがユーザーが探しているものに関連しており、ユーザーの質問に具体的に対処する方法で取り上げられていることを確認してください。

一元的な検索を設定する。 理想的な世界では、スペルを間違えたり、言語を間違えたりした場合でも検索が機能するはずです。 これまでのところ、Confluence での検索では満足できるものではありません。 多数の製品があり、ドキュメントが一般的な場合は、ユーザーがいるページに合わせて検索を調整します。 この場合、メイン ページの検索はすべての製品に対して機能しますが、すでに特定のセクションにいる場合は、そのセクション内の記事に対してのみ機能します。

コンテンツとパンくずリストを追加する。 各ページにメニューとブレッドクラム (ユーザーが現在のページへのパスを表示し、任意のレベルに戻ることができる) があると便利です。 古い ISPsystem ドキュメントでは、コンテンツにアクセスするには記事を終了する必要がありました。 不便だったので新しいものに直しました。

製品にリンクを配置する。 人々が同じ質問で何度もサポートに来る場合は、その解決策を示すヒントをインターフェースに追加するのが合理的です。 ユーザーがいつ問題を経験しているかに関するデータや洞察がある場合は、メーリング リストでユーザーに通知することもできます。 彼らに懸念を示し、サポートの負担を軽減してください。

ポップアップ ウィンドウの右側には、ISPmanager のドメイン管理セクションでの DNSSEC の設定に関する記事へのリンクがあります。

ドキュメント内で相互参照を設定する。 相互に関連する記事は「リンク」する必要があります。 記事が連続している場合は、各テキストの最後に必ず前後の矢印を追加してください。

おそらく、人は最初に自分の質問に対する答えをあなたではなく検索エンジンに探しに行くでしょう。 技術的な理由からドキュメントへのリンクがないのは残念です。 したがって、検索エンジンの最適化に注意してください。

問題 4. 古いレイアウトが認識を妨げる

不適切なテキストに加えて、ドキュメントは設計によって損なわれる可能性があります。 人々はよく書かれた資料を読むことに慣れています。 ブログ、ソーシャルネットワーク、メディア - すべてのコンテンツは、美しいだけでなく、読みやすく、目に心地よいものとして表現されています。 したがって、以下のスクリーンショットのようなテキストを見ると、人の痛みが簡単に理解できます。

この記事には非常に多くのスクリーンショットとハイライトが含まれているため、役に立ちませんが、認識の妨げになるだけです (画像はクリック可能です)

大量の効果を含むドキュメントを長々と読むべきではありませんが、基本的なルールを考慮する必要があります。

レイアウト。 本文のテキストの幅、フォント、サイズ、見出し、パディングを決定します。 デザイナーを雇って仕事を引き受けるか、自分で行うかについては、アルチョム・ゴルブノフの本「タイポグラフィーとレイアウト」を読んでください。 レイアウトのビューは XNUMX つだけ表示されていますが、これで十分です。

退院。 テキスト内で何を強調する必要があるかを判断します。 通常、これはインターフェイス、ボタン、コード挿入、設定ファイル、「注意してください」ブロック内のパスです。 これらの要素の配分を決定し、規制に記録します。 分泌物が少ないほど良いことを覚えておいてください。 多いと文字がうるさくなります。 引用符であっても、あまり頻繁に使用するとノイズが発生します。

スクリーンショット。 どのような場合にスクリーンショットが必要になるかについてチームと合意します。 すべてのステップを説明する必要はまったくありません。 多数のスクリーンショット。 ボタンが別々になると、認識が妨げられ、レイアウトが損なわれます。 スクリーンショットのハイライトや署名のサイズ、形式を決定し、規定に記録します。 イラストは常に書かれている内容と一致しており、関連性がある必要があることに注意してください。 繰り返しになりますが、製品が定期的に更新される場合、全員を追跡するのは困難になります。

テキストの長さ。 過度に長い記事は避けてください。 それらを部分に分割し、それが不可能な場合は、記事の先頭にアンカー リンクを含むコンテンツを追加します。 記事を視覚的に短くする簡単な方法は、狭い範囲の読者が必要とする技術的な詳細をネタバレの下に隠すことです。

フォーマット。 記事内でテキスト、ビデオ、画像などの複数の形式を組み合わせます。 これにより認識が改善されます。

美しいレイアウトで問題を隠そうとしないでください。 正直に言うと、私たち自身も「ラッパー」が古いドキュメントを保存してくれることを期待していましたが、うまくいきませんでした。 テキストには視覚的なノイズと不必要な詳細が非常に多く含まれていたため、規制や新しいデザインは無力でした。

上記の多くは、ドキュメントに使用するプラットフォームによって決まります。 たとえば、Confluence があります。 私も彼に手を加えなければなりませんでした。 興味があれば、Web 開発者のストーリーをお読みください。 パブリックナレッジベースの Confluence: デザインの変更と言語による分離の設定.

どこから改善を始めるべきか、そして生き残るにはどうすればよいか

ドキュメントが ISP システムと同じくらい膨大で、どこから始めればよいかわからない場合は、最大の問題から始めてください。 クライアントは文書を理解していません - 文章を改善し、規制を作り、ライターを訓練します。 ドキュメントが古いため、内部プロセスに注意してください。 最も人気のある製品に関する最も人気のある記事から始めます。サポートに問い合わせたり、サイト分析や検索エンジンのクエリを調べたりします。

すぐに言ってみましょう - それは簡単ではありません。 そして、それはすぐには機能しそうにありません。 始めたばかりで、すぐに正しいことをしない限り。 私たちが確かに知っていることの XNUMX つは、時間の経過とともに状況は改善されるということです。 しかし、プロセスは決して終わりません:-)。

出所： habr.com