Organizing large documents

如何将大量的信息组织成连贯一致有逻辑的文档或者网站？或者说，如何将一个混乱的文档或网站变得更容易理解，更为有用？如下技巧可以帮你：

• 将一个大的文档拆成文档集。
• 重新组织文档。
• 为文档增加目录导航。
• 逐步披露信息。

何时该写大文档

你可以将一系列信息组织成较长的独立文档或一组较短的相互关联的文档。相互关联的短文档通常以网站、WiKi或者类似的结构发布。

有的读者对较长文档的态度更为积极。假设为两个假设读者来编写文档，他们的观点如下：

• Hong觉得长篇文档读起来既困难又让人迷惑，他更喜欢使用网站的查找功能来查找问题的答案。
• Rose很擅长阅读大型文档，经常使用浏览器的内置页面搜索功能在当前页面中查找有用的信息。

所以，是将文档写成单个文档，还是网站上的一组文档？可以参考如下准则：

• 操作指南、介绍性概述和概念性指南，在针对该主题的新手时，通常较短的文档效果会更好。例如，对你的主题完全陌生的读者，可能难以记住许多新术语、概念和事实。请记住，你的读者阅读你的文档，可能是为了快速了解该主题。
• 深入性教程、最佳实践指南和命令行参考页面可以写成较长的文档，尤其是当你的目标读者是已经对该工具或主题有一定经验的人时。
• 一个出色的教程，可以通过叙述，指引读者在完成较长文档内的一系列相关任务。然而，即使是大型教程，有时也可以通过将其拆成更小的部分受益。
• 许多较长的文档，并非旨在只被阅读一次。例如，用户经常会在参考页面检索对某个命令或者标志的解释。

本单元的其余部分涵盖可用于编写例如教程或概念指南的较长文档的技巧。

对文档进行组织

本节介绍了规划较长文档的一些技巧，包括创建大纲或起草序言。写完文档的初稿后，你可以对照大纲和序言来审阅你的文档，以此确保你没有漏掉一些最初打算涵盖的内容。

创建文档大纲

首先创建结构性大纲，可以帮你对文档分组，并帮你确定哪个地方需要呈现更多细节。与此同时，大纲可以让你在真正动手写作前，方便地调整各主题的位置。

可以将大纲作为文档的简单叙述。编写大纲没有标准的方法，但以下指南提供了可能对你有用的实用技巧：

• 在要求读者执行某个任务前，请先解释为什么他们要做这个。例如，如下项目符号列表是一个审查和改进网页可访问性教程的大纲：

  • Introduce a browser plugin that audits the accessibility of web pages; explain that the reader will use the results of the audit report to fix several bugs.
  • List the steps to run the plugin and audit the accessibility of a web page.

• 将大纲的每个步骤限定在描述某个概念或完成某个特定的任务。

• 构建大纲，以确保在文档介绍的是与读者最相关的内容。例如，你的读者如果刚开始了解基础知识，很可能不需要或者不想在文档介绍部分看到项目的历史信息。若你认为项目历史信息是有必要的，应该在文末加上此类信息的链接。

• 在介绍某个概念后，给读者展示如何在示例项目或者他们自己的工作中应用它。在概念信息和实际操作之间交替，是一种非常引人入胜的学习方式。

• 若你正在与一组将要审查和测试你的文档的贡献者一起工作，那么大纲尤其有用。开始写全文草稿前，请先让文档的贡献者帮你审阅大纲。

文档大纲练习

如下是一篇长教程序言部分的大纲，请检查并改进它。你可以：

• 重排主题顺序。
• 添加你认为序言部分中应该有的主题。
• 移除你认为与序言部分无关的主题。

## 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.

当你完成草稿后，审阅整篇文档是否和概述中预设的期望一致。你的序言是否有精准地概述你想要呈现的主题？可以将这个文档审阅过程视作某种形式对文档的质量测试(QA)。

序言练习

假设有个叫做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.

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.

添加文档导航

为你的文档添加导航目录和“路标”，确保你的读者在卡住时可以找到他们需要的信息。

清晰的文档导航包括：

• 介绍和总结段落
• 清晰的有逻辑的主题延伸
• 帮助理解主题的标题和子标题
• 显示用户在文档中位置的目录菜单
• 指向相关资源和更深入内容的链接
• 指向下一步学习内容的链接

使用基于任务的标题

选择指引读者执行某项任务的标题，避免在标题内使用不熟悉的术语或者工具。例如，假设你的文档描述的是创建网站的过程。为了创建这个网站，用户必须初始化Froobus框架。而为了初始化Froobus框架，读者必须执行carambola命令行工具。第一眼看上去，在序言章节中使用如下标题是符合逻辑的：

• Running the carambola command
• Initializing the Froobus framework

除非你的读者非常熟悉文档主题有关术语和概念，否则更建议你使用更为人熟悉的标题。例如：Creating the site。

标题后跟随文字

大多数读者会希望能在文档每个标题后至少跟随一个简单的介绍。避免在二级标题后马上跟一个三级标题，例如：

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

如果在上述例子中加一些简单的介绍，可以给读者以指引：

## 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

标题练习

通过浏览文档导航，读者可以方便地找到使用你的工具所需的信息。通常来说，一个清晰且组织良好的目录或大纲就像一张地图，可以帮助读者熟悉你的工具的功能。

请对如下目录做改进。你可以重排、添加或者删除项目，也可以添加辅助条目。

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

逐步披露信息

对于许多喜欢按照自己的节奏阅读文档的读者来说，学习新概念、想法和技术可能是一种有益的体验。 然而，过快地面对太多的新概念和知识可能会让人不知所措。 读者更更有可能接受逐步向他们披露新信息的较长文档。 以下技巧可以帮助你逐步披露信息：

• 在使用新术语或新的概念前后，对术语或概念进行介绍。
• 打破“文字墙”。避免在当页面出现大段大段的文字，在适当的地方加入表格、图标、列表和标题。
• 拆解长步骤。如果你的列表描述一个长且复杂的步骤，请尝试将它重排成多个较短的列表，每个列表描述一个子步骤。
• 从简单的例子和说明开始，逐渐介绍更有趣更复杂的技术。例如，在创建网页表单的教程中，可以先介绍文本框，然后再介绍下拉菜单，图像或者其他表单内容。

Reference

原文：https://developers.google.com/tech-writing/two/large-docs