kanachi-blog

ドキュメントが優れているのは目的にかなっている場合である。

目的：ユーザーの特定の行動を促進することと、組織のゴールを達成することです。

• 機能品質：ドキュメントの目的やゴールが達成されているかどうか
  • アクセシビリティがあること
    • 言語
      • 読み手の言語で書かれている
    • 読解レベル
      • 小学校高学年レベルでも理解できる文章
      • 専門用語は説明なしには使わない
    • スクリーンリーダーによるアクセス
      • グラフィック・図・ビジュアルにはすべて、代替テキストを付与する
      • リンクしている映像にはすべて、キャプションと字幕を付けるとよいでしょう。
  • 目的があること
    • ドキュメントの目的と、読み手が達成できることをドキュメントに明確に書いておく
    • タイトルと最初の段落の両方に、ドキュメントの目的と、読み手が達成できることを書いておくと良い
  • 見つけやすいこと
    • どれくらい簡単に読み手がコンテンツにたどり着けるか、コンテンツ内を読み進めることができるかを表す指標
    • サイト全体における現在地を表示して、できるだけ多くのコンテキストを各ドキュメントで提供するとよい
  • 正確であること
    • ドキュメント内のコンテンツがどの程度正しいか、および信用できるかを表す指標
  • 完全であること
    • ユーザーの目的が達成されるために必要な情報がすべてドキュメントに含まれている
    • 網羅性の高さ的なこと
• 構造品質：ドキュメント自体がうまく書かれているか、うまく構成されているか
  • Clear（明確な）
    • ドキュメントをいかに簡単に理解できるかを表す指標です。ドキュメントの明確さは、提供している情報を読み手がどのぐらい簡単に取り込めるか、および読み手がうまくできる自信をどれほどもてるか
    • 具体的には以下のようなドキュメントが明確である
      • うまく定義された、正しい順序で並んでいる見出しによって、トピックが論理的に筋が通っている
      • ドキュメントの目的が明確である
      • 読み手が理解しやすい方法で、手順が構成されている
      • 読み手が行き詰まりやすい場所に対して指摘をしたり図を挿入するなど、対策を講じている
  • Concise（簡潔な）
    • 簡潔さの的を射た定義は、短くて分かりやすいことです
    • 簡潔なドキュメントには、全体的に読み手に関連する情報とゴールに関する情報のみが含まれています
    • 読み手の理解を妨げるものはすべて取り除き、関連はしているもののすぐに必要ではないものにはリンクを張っておく
  • Consistent（一貫している）
    • 以下の3点がドキュメント全体で同一であることを意味します。
      • コンテンツの構造
      • 導入するコンセプト
      • 言葉の選択

https://www.amazon.co.jp