キーワードを挙げ、トピックへの道しるべを示す
// Copyright 2025 Google LLC // SPDX-License-Identifier: Apache-2.0 /// [MARC 21 レコードリーダー][leader]のパース済み表現。 /// /// MARC リーダーには、レコードの残りの部分をどのように解釈するかを規定 /// するメタデータが含まれます。 /// /// [leader]: https://www.loc.gov/marc/bibliographic/bdleader.html pub struct Leader { /// スキーマと、その後に続く有効なデータフィールドの集合を決定します。 /// /// リーダーの byte 6 にエンコードされています。 pub type_of_record: char, /// より大きな著作物内の記事に対する "773 Host /// Item Entry" のような関連フィールドをパースするかどうかを示します。 /// /// リーダーの byte 7 にエンコードされています。 pub bibliographic_level: char, // ... その他のフィールド } /// [MARC 21 レコードリーダー][leader]をパースします。 /// /// リーダーは固定長の 24 バイトのフィールドとしてエンコードされており、 /// レコードの残りの部分の意味的な解釈を決定するメタデータを含みます。 /// /// [leader]: https://www.loc.gov/marc/bibliographic/bdleader.html pub fn parse_leader(leader_bytes: &[u8; 24]) -> Result<Leader, MarcError> { todo!() } #[derive(Debug)] pub enum MarcError {}
-
動機: ドキュメントの読者は、好きな小説の会話文を読むように、あなたの doc comment の大半を精読するわけではありません。
ユーザーはたいてい、その場で解決しようとしている問題に関係する ドキュメントの箇所を見つけるために、ざっと読み、拾い読みします。
自分に関係のあるキーワードや、道しるべになりそうな語を見つけると、 ユーザーは文書化されている対象の前後の文脈を探し始めます。
-
クラスに質問: ドキュメントでは何を探しますか? ここでは、一般的に ドキュメントに求める価値ではなく、その場その場の情報探索に注目してください。
-
キーワードは段落のなるべく冒頭で挙げる。
これはざっと読むことや拾い読みの助けになります。段落の最初の数語が 最も目に入りやすいからです。
ざっと読むことや拾い読みは、ユーザーがテキスト内を素早く移動する助けに なります。キーワードをできるだけ段落の冒頭近くに置くことで、関連情報 を見つけたかどうかをより早く判断できます。
-
道しるべは示す。ただし説明しすぎない。
ユーザーが API 設計者と同じドメイン知識を持っているとは限りません。
本筋ではない専門用語や頭字語に触れる場合は、初心者がすぐに追加で 調べられるだけの十分な文脈を持ち込むようにしてください。
-
道しるべの提示は自然に起こることもよくあります。たとえば、さまざまな プロトコルに言及するネットワーキングライブラリを考えてみてください。 しかし、自然にそうならない場合は、何に触れるべきかを選ぶのが難しく なります。
経験則: API 開発者は「初心者が自分の文書化しているものに出会ったら、 どの情報源を調べるだろうか。また、紛らわしい誤った手がかりを追って しまう可能性はあるだろうか」と自問すべきです。
ユーザーには、自分で主題を調べられるだけの十分な情報を与えるべきです。
-
すでに扱った、命名規則を含む API の予測可能性も、道しるべの一形態です。