7. リストとテーブル
優れたリストは技術的な混沌に秩序をもたらします。技術文書の読者は一般的に言ってリストが大好きなので、散文をリストにする機会を常に探るようにしましょう。
正しい種類のリストを選ぶ
テクニカルライティングでは次の種類のリストが主に使われます:
- 箇条書き (bulleted list)
- 番号付きリスト (numbered list)
- 埋め込みリスト (embedded list)
箇条書きは要素に順序がないときに、番号付きリストは要素に順序があるときに使ってください。言い換えると:
- 箇条書きの要素を並べ替えてもリストの意味は変わりません。
- 番号付きリストの要素を並べ替えるとリストの意味が変わります。
例えば、次のリストでは要素を並べ替えてもリストの意味が変わらないので、箇条書きを使っています:
Bash provides the following string manipulation mechanisms:
- deleting a substring from the start of a string
- reading an entire file into one string variable
(Bash は次の文字列操作機構を持つ:
- 文字列の先頭から部分文字列を削除する。
- ファイル全体を一つの文字列変数に読み込む。)
一方、次のリストでは要素の順番を変えると意味が変わるので、番号付きリストを使っています:
Take the following steps to reconfigure the server:
- Stop the server.
- Edit the configuration file.
- Restart the server.
(サーバーを設定するには、次の手順を踏むこと:
- サーバーを停止する。
- 設定ファイルを編集する。
- サーバーを再起動する。)
埋め込みリスト (embedded list または run-in list) は文の中に要素を詰め込んだリストのことを言います。例えば次の例文は四つの要素を持った埋め込みリストを持ちます:
The llamacatcher API enables callers to create and query llamas, analyze alpacas, delete vicugnas, and track dromedaries.
(llamacatcher API を使うと、ラマの作成・クエリ・アルパカの解析・ヴィクーニャの削除・ヒトコブラクダの追跡が呼び出し側から可能になる。)
一般的に言って、埋め込みリストは技術情報を提示するのに適していません。埋め込みリストは箇条書きまたは番号付きリストに変換するようにしてください。例えば埋め込みリストを持つ上の例文は次のようにできます:
The llamacatcher API enables callers to do the following:
- Create and query llamas.
- Analyze alpacas.
- Delete vicugnas.
- Track dromedaries.
(llamacatcher API を使うと、呼び出し側は次のことが可能になる:
- ラマの作成とクエリ
- アルパカの解析
- ビクーニャの削除
- ヒトコブラクダの追跡)
練習問題
次の段落を一つ以上のリストを使って書き換えてください:
Today at work, I have to code three unit tests, write a design document, and review Janet's latest document. After work, I have to wash my car without using any water and then dry it without using any towels.
(今日は仕事で三つのユニットテストを書き、デザインドキュメントを書き、ジャネットの最新のドキュメントをレビューしなければならない。仕事の後は、水を使わずに車を洗ってタオルを使わずに車を乾かさなければならない。)
リストに繋がる文章を加えるのを忘れないでください。
解答例を示します:
I must do the following at work today:
- Code three unit tests.
- Write a design document.
- Review Janet's latest document.
After work, I must do the following:
- Wash my car without using any water.
- Dry my car without using any towels.
(私は今日仕事で次のことをしなければならない:
- 三つのユニットテストを書く。
- デザインドキュメントを書く。
- ジャネットの最新のドキュメントをレビューする。
私は仕事の後に次のことをしなければならない:
- 水を使わずに車を洗う。
- タオルを使わずに車を乾かす。)
別の解答例を示します:
I must do the following tasks today:
- At work:
- Code three unit tests.
- Write a design document.
- Review Janet's latest document.
- After work:
- Wash my car without using any water.
- Dry my car without using any towels.
(私は今日次のタスクをこなさなければならない:
- 仕事で:
- 三つのユニットテストを書く。
- デザインドキュメントを書く。
- ジャネットの最新のドキュメントをレビューする。
- 仕事の後で:
- 水を使わずに車を洗う。
- タオルを使わずに車を乾かす。)
リストを並列に保つ
分かりやすいリストと分かりにくいリストの違いは何でしょうか？ 分かりやすいリストは並列 (parallel) であり、分かりにくいリストは並列でない傾向があります。並列なリストでは全ての要素が同じ種類に属します。言い換えると、要素間で次のパラメータが一致します:
- 文法
- 論理的カテゴリ
- 単語先頭の大文字
- 句読点の使い方
逆に言うと、並列でないリストでは少なくとも一つの要素がこの一貫性の基準を満たしません。
例えば次のリストは並列です。なぜなら要素がどれも複数形 (文法) の食べ物 (論理的カテゴリ) であり、小文字で始まっていて (単語先頭の大文字) 最後にピリオドとコンマが付かない (句読点) からです:
- carrots (ニンジン)
- potatoes (ジャガイモ)
- cabbages (キャベツ)
一方で、次のリストは四つの特徴のどれを見ても明らかに並列とは言えません:
- carrots (ニンジン)
- potatoes (ジャガイモ)
- The summer light obscures all memories of winter. (夏の日差しは冬の記憶を全て覆い隠す。)
次のリストは、要素がどれも大文字で始まる句読点を持った完全な文なので、並列です。
- Carrots contain lots of Vitamin A. (ニンジンにはたくさんのビタミン A が含まれる。)
- Potatoes taste delicious. (ジャガイモは美味しい。)
- Cabbages provide oodles of Vitamin K. (キャベツはビタミン K をどっさり提供する。)
読者はリストの最初の要素を見て、以降の要素で繰り返されるであろうパターンを想像します。
練習問題
次のリストが並列かどうかを答えてください。
- Broccoli inspires feelings of love or hate. (ブロッコリーは愛または憎しみの感情を想起させる。)
- Potatoes taste delicious. (ジャガイモは美味しい。)
- Cabbages. (キャベツ。)
このリストは並列ではありません。最初の二つの要素は完全な文ですが、三つ目の要素は文となっていません (三つ目の要素が大文字で始まってピリオドで終わることに惑わされないでください)。
練習問題
次のリストが並列かどうかを答えてください。
- The red dots represent sick trees. (赤い点は病気の木を表す。)
- Immature trees are represented by the blue dots. (若い木は青い点で表される。)
- The green dots represent healthy trees. (緑の点は健康な木を表す。)
このリストは並列ではありません。一つ目と三つ目の要素は能動態ですが、二つ目の要素が受動態となっています。
番号付きリストの要素は命令形で始める
番号付きリストでは全ての要素を命令形の動詞で始められないか考えるようにしてください。命令形の動詞は「言い付け」であり、"open (開け)" や "start (開始せよ)" がその例です。例えば次の番号付きリストの各要素はどれも命令形の動詞で始まっています:
- Download the Frambus app from Google Play or iTunes. (Frambus アプリを Google Play または iTunes からダウンロードせよ。)
- Configure the Frambus app's settings. (Frambus アプリの設定を変更せよ。)
- Start the Frambus app. (Frambus アプリを開始せよ。)
次の番号付きリストは最初の二つの要素が命令形の動詞で始まっているものの三つ目の要素がそうでないので、並列ではありません:
- Instantiate the
Froobusclass. (Froobusクラスをインスタンス化せよ。) - Invoke the
Froobus.Salmonella()method. (Froobus.Salmonella()メソッドを起動せよ。) - The process stalls. (プロセスがストールする。)
練習問題
次のリストを並列にしてください。答のリストの各要素は命令形の動詞で始めてください。
- Stop Frambus (Frambus を停止せよ)
- The key configuration file is
/etc/frambus. Open this file with an ASCII text editor. (重要な設定ファイルは/etc/frambusである。このファイルを ASCII テキストエディタで開け。) - In this file, you will see a parameter named Carambola, which is currently set to the default value (32). Change this value to 64. (このファイルの中に Carambola という名前のパラメータがあり、それは現在デフォルト値 (32) に設定されている。この値を 64 に変更せよ。 )
- When you are finished setting this parameter, save and close the configuration file (このパラメータの設定が終わったら、設定ファイルを保存して終了せよ。)
- now, start Frambus again. (そうしたら、Frambus を再起動せよ。)
解答例を示します:
- Stop Frambus. (Frambus を停止せよ。)
- Open the key configuration file,
/etc/frambus, with an ASCII text editor. (設定ファイル/etc/frambusを ASCII テキストエディタで開け。) - Change the Carambola parameter from its default value (32) to 64. (Carambola パラメータをデフォルト値 (32) から 64 に変更せよ。)
- Save and close the configuration file. (設定ファイルを保存し閉じろ。)
- Restart Frambus. (Frambus を再起動せよ。)
要素に正しく句読点を打つ
リストの要素が文のときは、大文字と句読点の使い方を通常の文と同じにしてください。そしてリストの要素が文でないなら、全て小文字にしてピリオドを打たないでください。例えば次のリストの要素は文なので、最初の単語 Most の M を大文字にして、文の最後にピリオドを打ちます:
- Most carambolas have five ridges. (多くのスターフルーツは五つの稜線を持つ。)
一方で次のリストの要素は文ではないので、the の t は小文字にしてピリオドを打ちません:
- the color of lemons (レモンの色)
分かりやすい表を作る
何かを分析するときの頭脳は表が大好きです。いくつかの段落と一つの表からなるページが与えられると、エンジニアの目は表に引き寄せられます。
表を作るときは次のガイドラインを意識してください:
- 各列に意味のある見出しを付ける。列にあるのが何なのかを読者に想像させない。
- 表のセルにテキストを入れ過ぎないようにする。セルに三文以上が入るなら、他のフォーマットの方が適していないかを考える。
- 異なる列に異なるデータを入れても構わないが、列の中ではデータを並列に保つようにする。例えば、一つの列の中に数値データと有名なサーカス象の名前を混ぜるべきではない。
注意: 表の描画はフォームファクタに影響を受けます。例えばノート PC で素晴らしく見える表であっても、スマートフォンからは崩れて見えるかもしれません。
リストと表を全て紹介する
リストや表を使うときは、それが何を表すのかを読者に伝える紹介文を添えることを推奨します。言い換えると、リストや表は文脈と共に提示してください。こういった紹介文の最後はピリオドではなくコロンとします。
絶対に必要というわけではありませんが、リストや表が続く紹介文には "following (次の)" という単語を含めることを私たちは推奨します。紹介文の例を次に示します:
The following list identifies key performance parameters:
(次のリストに主要なパフォーマンスパラメータを示す:)
Take the following steps to install the Frambus package:
(Frambus パッケージをインストールするには次のステップを踏むこと:)
The following table summarizes our product's features against our key competitors' features:
(我々のプロダクトの機能と競争相手の機能を次の表にまとめる:)
練習問題
次の表に対する紹介文を書いてください:
| Languages (言語) | Inventor (開発者) | Year Introduced (発表年) | Key Feature (主な機能) |
|---|---|---|---|
| Lisp | John McCarthy (ジョン・マッカーシー) | 1958 | recursion (再帰) |
| C++ | Bjarne Stroustrup (ビャーネ・ストラウストラップ) | 1979 | OOP |
| Python | Guido van Rossum (グイド・ヴァン・ロッサム) | 1994 | simplicitfy (単純さ) |
この表に対する紹介文として考えられる文を示します:
The following table contains a few key facts about some popular programming languages:
(いくつかの有名なプログラミング言語に関する重要な事実を次の表に示す:)
The following table identifies the inventor, year of invention, and key feature of three popular programming languages:
(三つの有名なプログラミング言語の開発者・発表年・主要な機能を次の表にまとめる:)