Open AI が推奨する良いドキュメントを書く Tips についての紹介

田中太郎

Open AI Cookbook を試している際に、What makes documentation goodという面白い記事があったので紹介してみます。

注意点として下記の内容はほぼ基本機械翻訳なのであしからず 📝 。


以下は、役立つ情報を他の人の頭に入れるためのドキュメントに関するヒントです。これらのヒントに従って、より良いドキュメントを作成してください。

ドキュメントをスキムしやすくする

  • ドキュメントはスキムしやすくしてください。

    • 読者の多くは、問題を解決する部分が何かを評価しようとして、上から下へと直線的に読むことはありません。彼らはジャンプして、彼らの問題を解決するかどうかを評価しようとします。彼らの検索時間を減らし、成功の可能性を高めるために、ドキュメントをスキムしやすくしてください。

  • セクションごとにタイトルを付けてコンテンツを分割してください。

    • セクションタイトルは案内標識の役割を果たし、読者にフォーカスするかどうかを伝えます。

  • 抽象的な名詞よりも情報を含む文をタイトルとして選択してください。

    • たとえば、「Results」というタイトルを使用する代わりに、「Streaming reduced time to first token by 50%」というタイトルを使用すると、読者に情報がすぐに提供されるため、余分なジャンプの負担が軽減されます。

  • 目次を含めてください。

    • 目次は、ハッシュマップがリンクリストよりも高速な検索を持つように、読者が情報をより速く見つけるのに役立ちます。目次には、ドキュメントに関するヒントが含まれており、それが読む価値があるかどうかを理解するのに役立ちます。

  • 段落を短く保ちます。

    • 短い段落はスキムしやすくなります。重要なポイントがある場合は、それを独立した 1 文の段落に入れて、見逃される可能性を減らしてください。長い段落は情報を隠してしまうことがあります。

  • 段落やセクションを、独立したプレビューを与える短いトピックセンテンスで始めてください。

    • スキムする際、人々はセクションの最初の単語、最初の行、最初の文に不釣り合いに注意を払います。これらの文を以前のテキストに依存しないように書いてください。

  • トピックセンテンスの始めにトピックワードを置いてください。

    • 読者は、段落の内容を知るために 1 語または 2 語しか読まなくてもよいように、トピックセンテンスを書く際には、文のトピックを文の先頭に置くことを好みます。

  • まず最初に要点を示してください。

    • 最も重要な情報をドキュメントやセクションのトップに配置してください。Socratic なビッグビルドアップを書かないでください。手順を結果の前に紹介しないでください。

  • ブルーレットや表を使用してください。

    • ブルーレットリストや表を使用すると、ドキュメントがスキムしやすくなります。頻繁に使用してください。

  • 重要なテキストを太字にしてください。

    • 読者がそれを見つけやすくするために、重要なテキストを太字にすることを恐れないでください。

良い文章を書く

  • 書き方の良くないテキストは読むのに負担がかかります。

    • 読みやすく書くことで、読者にかかる負担を最小限に抑えてください。

  • 文をシンプルにしてください。

    • 長い文は 2 つに分割してください。副詞を削除してください。不要な単語やフレーズを削除してください。適用可能な場合は命令文を使用してください。書籍に書いてある通りにしてください。

  • 曖昧さなく解釈できる文を書いてください。

    • 例えば、「Title sections with sentences」という文を考えてみてください。読者が「Title」という単語を読むと、その単語が名詞か動詞か形容詞かまだ脳がわかりません。その後の文を解釈しながら脳を追跡するために、少しの脳のパワーが必要になり、脳が意味を誤予測した場合にはヒッチが発生する可能性があります。もっと簡単に解釈できる文を好みます（例：「Write section titles as sentences」）たとえ長くても。同様に、「Bicycle clearance exercise notice」という名詞句を避けてください。これには余分な労力がかかる可能性があります。

  • 左枝分かれの文を避けてください。

    • 言語学の木は、文の中の単語の関係を示します。左枝分かれの木は、右枝分かれの文よりも、読者に多くのことを記憶させる必要があります。例えば、「To make pancakes, you need flour, eggs, milk, butter, and a dash of salt」という右枝分かれのバージョンは、「You need flour, eggs, milk, butter and a dash of salt to make pancakes.」という左枝分かれの文のような、より読みやすいバージョンがあります。読者が単語をしばらく保持する必要がある文を見つけ、それを再構築できるか確認してください。

  • 示唆代名詞（たとえば「これ」）を避けてください。特に文をまたぐ場合は。

    • 例えば、「Building on our discussion of the previous topic, now let’s discuss function calling」と言う代わりに、「Building on message formatting, now let’s discuss function calling」と言います。第 2 の文は理解しやすいので、以前のトピックを記憶する負担がありません。示唆代名詞を全てカットする機会を探してください。たとえば、「Now let’s discuss function calling」と書いてください。

  • 一貫性を保つことが重要です。

    • 人間の脳は驚異的なパターンマッチャーです。不一致は読者をいらいらさせたり、気を散らしたりします。タイトルケースをどこでも使用している場合は、タイトルケースを使用してください。すべてのクックブックノートブックにアンダースコアとセンテンスケースを使用している場合は、アンダースコアとセンテンスケースを使用してください。「あれ、それ変だな」と読者が感じることのないようにしてください。彼らが内容に集中できるように、一貫性を保ってください。

  • 読者が何を考えているか、または何をすべきかを読者に教えないでください。

    • 「Now you probably want to understand how to call a function」といった文や「Next, you’ll need to learn to call a function」といった文は避けてください。これらの例は、読者の心理状態を仮定しているため、読者をいらいらさせたり、信頼性を損なう可能性があります。読者の状態を仮定しないフレーズを使用してください。たとえば、「To call a function, …」と書いてください。

幅広く役立つことが重要です

  • 人々は、知識、言語能力、忍耐力のレベルが異なります。

    • 経験豊富な開発者をターゲットにしていても、できるだけ多くの人に役立つようなドキュメントを作成するようにしてください。

  • 単純に書いてください。

    • 自分が必要な以上に単純に説明してください。多くの読者は英語を母国語として話さないかもしれません。多くの読者は技術用語について非常に混乱しているかもしれず、英文の解析に余分な脳力を使う余裕がほとんどありません。単純に書いてください（しかし、過度に単純化しないでください）。

  • 略語を避けてください。

    • IF の代わりに、instruction following と書いてください。RAG の代わりに、retrieval-augmented generation（または私の好みの用語：the search-ask procedure）と書いてください。

  • 潜在的な問題の解決策を提供してください。

    • パッケージのインストール方法や環境変数の保存方法が 95％の読者が知っているとしても、それを積極的に説明することが価値があります。説明を含めることは専門家にとって費用がかかりません - 彼らはそれをスキムすることができます。しかし、説明を省略することは初心者にとって費用がかかります - 彼らは立ち往生するか、私たちを見捨てるかもしれません。JavaScript エンジニアや C++エンジニアでさえも、Python の初心者である可能性があることを覚えておいてください。少なくとも多くを説明しすぎるよりも、少なすぎるよりも、説明することを優先してください。

  • 特定で正確な用語を使用してください。

    • 隠語はよくありません。フィールドの新人向けにドキュメントを最適化してください。たとえば、「prompt」と書く代わりに「input」と書いてください。または、「context limit」と書く代わりに「max token limit」と書いてください。後者の用語の方が自明であり、ベースモデルの日々に開発された隠語よりも良いでしょう。

  • コード例を一般的でエクスポート可能なものにしてください。

    • コードのデモンストレーションでは、依存関係を最小限に抑えるようにしてください。ユーザーに追加のライブラリのインストールをさせないでください。さまざまなページやセクションの間を行ったり来たりする必要がありません。例をシンプルで自己完結的にしてください。

  • 価値に基づいてトピックを優先しましょう。

    • よくある問題をカバーするドキュメント（たとえば、トークンの数を数える方法）は、エモジデータベースを最適化する方法のドキュメントよりも数倍価値があります。それに応じて優先順位を付けてください。

  • 悪い習慣を教えないでください。

    • API キーをコードに保存してはいけない場合は、API キーをコードに保存する例を共有しないでください。

  • 広いオープニングでトピックを紹介してください。

    • 良いレコメンダーをプログラムする方法を説明する場合、YouTube の動画から Amazon の商品、Wikipedia まで、レコメンドがウェブ全体に広がっていることを簡単に触れてみてください。広いオープニングで狭いトピックを理解させると、人々が不確実な領域に飛び込む前に安心感を得るのに役立ちます。そして、テキストがうまく書かれていれば、それを既に知っている人でも楽しむことができます。

良い理由があるときにこれらのルールを破る

最終的には、最良だと思うことをしてください。ドキュメントは共感の表現です。読者の立場に立って、彼らに最も役立つと思われることをしてください。

まとめ

文章自体日本語翻訳だと分かりにくい部分がありますが、概ね英語で書かれている内容の意図は伝わります。 良いドキュメントを格上の様々な Tips について書かれている有用な資料です。特に読者の視点で考えてくださいという Tips が多いのが面白い点でした、人間の心理学的な側面がドキュメントを書く際に極めて重要になるので、自分が読者と仮定して文章を書くのが如何に重要かということを何度も例示しているのが印象的です。

以下は分かりにくい点

  • スキム(Skim)

    • "Skim"とは、「ざっと目を通す」という意味です。文章を速く読んで、大まかな内容を把握することを指します。ドキュメントをスキムするとは、ドキュメントを読みやすくするといった感じでしょうか

  • 示唆代名詞

    • これは指示代名詞でしょうね

この記事が気に入ったらサポートをしてみませんか？