3. 大規模なドキュメントの構成

収集した多くの情報を一つのドキュメントやウェブサイトとしてまとめるにはどうすればよいでしょうか？ 言い換えると、現在手にしている取っ散らかったドキュメントあるいはウェブサイトの断片を再構成して、読者が親しみやすく役に立つものとするにはどうすればよいでしょうか？ 試す価値のある戦略を示します:

いつ大きなドキュメントを書くべきか

収集した情報は一つの長いドキュメントにすることも、互いに関連した短いドキュメントの集合にすることもできます。短いドキュメントの集合はよくウェブサイトや wiki といった構造化されたフォーマットで公開されます。

長いドキュメントに対してポジティブに反応する読者もいればネガティブに反応する読者もいます。あなたが執筆中のドキュメントを読む人は次のような考えを持っているかもしれません:

では、あなたの持っている情報は一つのドキュメントにすべきでしょうか？ それともウェブサイトとして複数のドキュメントにすべきでしょうか？ 次の指針を考えてみてください:

この章の残りの部分ではチュートリアルや概念の説明などの長いドキュメントを書くときに役立つテクニックを説明します。

ドキュメントを構成する

この節ではアウトラインや序章の作成といった、大きなドキュメントを計画する上でのテクニックをいくつか示します。ドキュメントの初稿を書き終えたら要約や序章を確認して、最初に触れようと思っていたことが忘れられていないかを確認するようにしてください。

ドキュメントのアウトラインを作る

構造化された高いレベルのアウトライン (大筋) から文書を書き始めると、トピックをグループ化しやすくなり、説明が必要な部分が分かりやすくなります。またアウトラインから書き始めれば、本格的な執筆に取りかかる前にトピックをあちこち移動させて実験を行うことができます。

アウトラインをドキュメントの物語と考えると理解しやすいかもしれません。アウトラインを書く標準的なアプローチはありませんが、あなたにも役立つであろう実践的なテクニックを次に示します:

練習問題

次に示すのは長いチュートリアルの序章に対する高いレベルのアウトラインです。これをレビューし、改善してください。トピックの移動・追加・削除を行って構いません。

## The history of the project

Describes the history of the development of the project.

## Prerequisites

Lists concepts the reader should be familiar with prior to starting, as
well as any software or hardware requirements.

## The design of the system

Describes how the system works.

## Audience

Describes who the tutorial is aimed at.

## Setting up the tutorial

Explains how to configure your environment to follow the tutorial.

## Troubleshooting

Explains how to diagnose and solve potential problems that might occur when
working through the tutorial.

## Useful terminology

Lists definitions of terms that the reader needs to know to
follow the tutorial.

(## プロジェクトの来歴

このプロジェクトの開発の来歴を説明する。

## 前提条件

始める前に読者が知っておくべき概念をまとめる。
またソフトウェアとハードウェアの要件も示す。

## システムの設計

システムがどのように動くかを説明する。

## 読者

このチュートリアルが誰に向けられているかを説明する。

## チュートリアルのセットアップ

チュートリアルを追うための環境を設定する方法を説明する。

## トラブルシューティング

チュートリアル中に起こる可能性のある問題を診断・解決する方法を説明する。

## 便利な専門用語のまとめ

チュートリアルを読むときに知っておくべき用語の定義をまとめる。)

解答例を示します:

## Audience

Describes who the tutorial is aimed at.

## Prerequisites

Lists concepts the reader should be familiar with prior to starting, as
well as any software or hardware requirements.

## Setting up the tutorial

Explains how to configure your environment to follow the tutorial.

## Useful terminology

Lists definitions of terms that the reader needs to know to follow the
tutorial.

(## 読者

このチュートリアルが誰に向けられているかを説明する。

## 前提条件

始める前に読者が知っておくべき概念をまとめる。
またソフトウェアとハードウェアの要件も示す。

## チュートリアルのセットアップ

チュートリアルを追うための環境を設定する方法を説明する。

## 便利な専門用語のまとめ

チュートリアルを読むときに知っておくべき用語の定義をまとめる。)

ドキュメントの紹介文

読者はドキュメントの題材が自分にとって重要だと思わなければ、そのドキュメントを高い確率で無視します。最低限の判断材料を読者に提供するために、次の情報を含んだ紹介文を付けることを推奨します:

ただドキュメントは保守しやすい状態に保つべきなので、触れるトピック全てを紹介文に詰め込む必要はありません。

次の段落は上のリストで示した考え方を実践した例です。Froobus と呼ばれる架空のドキュメント公開プラットフォームの概要を説明しています:

This document explains how to publish Markdown files using the Froobus system. Froobus is a publishing system that runs on a Linux server and converts Markdown files into HTML pages. This document is intended for people who are familiar with Markdown syntax. To learn about the syntax, see the Markdown reference. You also need to be comfortable running simple commands in a Linux terminal. This document doesn't include information about installing or configuring a Froobus publishing system. For information on installing Froobus, see Getting started.

(このドキュメントは Froobus システムを使って Markdown ファイルを公開する方法を 説明する。Froobus は Linux サーバー上で動作するパブリッシングシステムであり、 Markdown ファイルを HTML ページに変換する。このドキュメントは Markdown の シンタックスを知っている人に向けて書かれている。Markdown のシンタックスについて 学ぶには Markdown reference を参照のこと。また Linux ターミナルで簡単な コマンドを問題なく実行できる必要もある。このドキュメントには Froobus パブリッシングシステムのインストールと設定の方法は含まれない。 Froobus のインストールについては Getting started にある。)

初稿を書き終えたら、ドキュメント全体が最初の概要に示した内容に合致しているかどうかを確かめてください。紹介文はあなたが触れたトピックの正確な概要となっていますか？ このレビューはドキュメントに対する品質保証の一種と言えます。

練習問題

この練習問題では、次の紹介文をレビュー・改善してもらいます。これは架空のプログラミング言語 F@ に対するベストプラクティスガイドです。関係ないと感じた情報を削除し、足りないと思った情報を追加してください。

This guide lists best practices for working with the F@ programming language. F@ was developed in 2011 as an open source community project. This guide supplements the F@ style guide. In addition to the best practices in this guide, make sure you also install the F@ command-line linter and run it on your code. The programming language is widely adopted in the health industry. If you have suggestions for additions to the list of best practices, file an issue in the F@ documentation repository.

(このガイドはプログラミング言語 F@ を使いこなすためのベストプラクティスをまとめたものである。F@ は 2011 年にオープンソースプロジェクトとして開発された。このガイドは F@ のスタイルガイドを捕捉するものである。このガイドにあるベストプラクティスに加えて、コマンドラインの F@ リンターをインストールしてコードに対して実行すること。プログラミング言語 F@ は健康産業で広く採用されている。もしベストプラクティスのリストへの追加の提案があるなら、F@ ドキュメントリポジトリに issue を立てること。)

解答例を示します:

This guide lists best practices for working with the F@ programming language. Before you review this guide, complete the introductory tutorial for new F@ developers. This guide supplements the F@ style guide. In addition to the best practices in this guide, make sure you also install the F@ command-line linter and run it on your code. If you have suggestions for additions to the list of best practices, file an issue in the F@ documentation repository.

(このガイドはプログラミング言語 F@ を使いこなすためのベストプラクティスをまとめたものである。このガイドを確認する前に、新しい F@ 開発者用の入門チュートリアルを完了すること。このガイドにあるベストプラクティスに加えて、コマンドラインのF@ リンターをインストールしてコードに対して実行すること。もしベストプラクティスのリストへの追加の提案があるなら、 F@ ドキュメントリポジトリに issue を立てること。)

ナビゲーションを追加する

ナビゲーションや道標を提供して、読者が探しているものや問題を解決する情報を確実に見つけられるようにしてください。

明快なナビゲーションの例を示します:

ドキュメントの見出しを作るためのテクニックを以降の節で示します。

タスクを示す見出しを使う

見出しには読者が取り組んでいるタスクを示してください。聞きなれない用語やツールを使った見出しは避けてください。例えば、新しいウェブサイトを作る手順をまとめたドキュメントを書いているとします。サイトを作るには Froobus フレームワークの初期化が必要で、そのためにコマンドラインツール carambola を実行しなければならないとしましょう。このとき、次のような行うべき操作を使った見出しが一見すると論理的に思えるかもしれません:

しかし読者がこのトピックの用語や概念に最初から精通していない限り、「サイトを作る」のような読者が理解できる見出しの方が適しています。

見出しの直後に文章を付ける

見出しのすぐ後にその節の簡単な紹介文が付いていれば、多くの読者はそれを喜んで読むでしょう。次の例のように、レベル 3 の見出しをレベル 2 の見出しの直後に置くのは避けてください:

## Creating the site
### Running the carambola command

(## サイトの作成
### carambola コマンドの実行)

この例では、短い説明文を付ければ読者を適切な方向に導くことができます:

## Creating the site

To create the site, you run the `carambola` command-line tool. The command
displays a series of prompts to help you configure the site.

### Running the carambola command

(## サイトの作成

サイトを作るには、コマンドラインツールの `carambola` を実行します。
このコマンドはサイトを設定するためのプロンプトをいくつか提示します。

### carambola コマンドの実行)

練習問題

ドキュメントを読者に上手く案内すれば、必要な情報の発見やあなたのツールを使った問題解決が簡単になります。明快でよく整理された目次やアウトラインはあなたのツールが持つ特定の機能へ読者を案内する地図のようなものです。

この練習問題では、次のアウトラインを改善してください。トピックの並び替え・追加・削除および二段目のエントリーの作成を行って構いません。

About this tutorial
Advanced topics
Build the asset navigation tree
Define resource paths
Defining and building projects
Launch the development environment
Defining and building resources
What's next
Define image resources
Audience
See also
Build an image resource
Define an image project
Build an image project
Setting up the tutorial
Select the tutorial asset root
About this guide

(このチュートリアルについて
高度なトピック
アセットナビゲーションツリーをビルドする
リソースパスを定義する
プロジェクトの定義とビルド
開発環境を起動する
ビルドリソースの定義
この次は？
画像リソースを定義する
対象読者
関連資料
画像リソースをビルドする
画像プロジェクトを定義する
画像プロジェクトをビルドする
チュートリアルのセットアップ
チュートリアルのアセットルートを選択する
このガイドについて)

## About this tutorial
### Audience
### About this guide
### Advanced topics
## Setting up the tutorial
### Select the tutorial asset root
### Launch the development environment
### Build the asset navigation tree
### Define resource paths
## Defining and building resources
### Define image resources
### Build an image resource
## Defining and building projects
### Define an image project
### Build an image project
## Defining and building databases
### Define a database
### Build a database
## Pushing, publishing, and viewing a database
### Push a database
### Publish a database
### View a database
## Configuring display rules for point data
### Define, configure, and build vector data
## See also
### Sample data files
## What's next

(## このチュートリアルについて
### 対象読者
### このガイドについて
### 高度なトピック
## チュートリアルのセットアップ
### チュートリアルのアセットルートを選択する
### 開発環境を起動する
### アセットナビゲーションツリーをビルドする
### リソースパスを定義する
## ビルドリソースの定義
### 画像リソースを定義する
### 画像リソースをビルドする
## プロジェクトの定義とビルド
### 画像プロジェクトを定義する
### 画像プロジェクトをビルドする
## データベースの定義とビルド
### データベースを定義する
### データベースをビルドする
## データベースのプッシュ・公開・閲覧
### データベースをプッシュする
### データベースを公開する
### データベースを閲覧する
## 点データに対する表示規則の設定
### ベクトルデータを定義・設定・ビルドする
## 関連資料
### サンプルデータファイル
## この次は？)

情報を少しずつ見せる

ドキュメントを自身に合ったペースで読み進められる多くの読者にとって、新しい概念・アイデア・テクニックの学習はやりがいのある体験です。しかし、たくさんの新しい概念や指示を立て続けに読者へ示せば、読者は圧倒されてしまうでしょう。それよりは、新しい情報を必要になったときに少しずつ読者に提供する長いドキュメントの方が受け入れやすいはずです。あなたのドキュメントで情報の公開を段階的にするためのテクニックを示します:

広告
このページの文章はテキストゆれないくんを使って校正されました。