Text that's difficult to read in paragraph form often becomes clear when put into a table. Tables clarify the relationships among information, and they're easy to scan. This topic provides the guidelines for the following aspects of tables:
- Introductory text for tables
- Table titles
- Column headers
- Table text
- Table footnotes
- Attribute or parameter tables in API documents
Example tables that reflect the guidelines are presented in a separate section at the end of this topic.
Don't create tables that are overly complex or that scroll horizontally. If a table has too much information, try to break it up into smaller tables.
Introductory text for tables#
In the text that precedes a table, introduce the table in a way that relates the table to the text. If the table immediately follows the reference to it, use a generic reference (such as the following table) even if the table has a title. Provide a link to a table title only when the table doesn't immediately follow the reference or when the table is in a different article or section.
To introduce a table, use a sentence (not a fragment), and end the sentence with a colon.
Tables should normally have titles (captions). However, some tables are closely associated with the surrounding text and don't require titles. For example, decision matrixes and tables within tasks, procedures, and tutorials don't require numbers or titles.
When creating table titles, use the following guidelines:
- Use sentence-style capitalization for table titles. However, for words that are always uppercase or always lowercase, match that case.
- Don't start a table title with an article (a, an, the).
- Don't end a table title with a period or colon.
- Place the title above the table, not below it, and tag it as bold.
- Don't manually number table titles. If titles should be numbered, the style sheet will number them.
- Make table titles concise; limit them to one line if possible.
- Make table titles descriptive:
- Avoid using a table title that duplicates a topic or section title.
- Ensure that no two table titles in an article or section are identical. To distinguish between the titles that are similar, add qualifiers.
- Don't include trademark symbols in table titles.
Use the following guidelines for text in column headers:
- Use sentence-style capitalization in column headers. However, for words that are always uppercase or always lowercase, match that case.
- Use singular nouns for column headers, unless the context requires otherwise.
- Don't end column headers with ellipses or colons.
Use the following guidelines for text in table cells:
- Use the same punctuation and capitalization guidelines that you use for text in lists. See List items.
- Make the entries in a table parallel. For example, in a column that describes options, be consistent in beginning the entries with a verb or noun.
- Avoid leaving a table cell blank. If no information is available for that cell, use Not applicable or None. Use the abbreviation NA only if space constraints exist. Don't use dashes. An exception is for matrix-type tables that use an X or other marker to indicate support. In such cases, blank cells are acceptable (see the third example at the end of this topic).
- When showing a notation (for example, a note or warning) in a table, use the guidelines in Notes and other notation types.
- If space in a table is constrained, you can use abbreviations and symbols that you wouldn't normally use in body text (such as % for percent).
- Don't use color to differentiate table text.
If a notation (for example, a note or warning) applies to the entire table, place the content in a regular notation preceding the table. If a notation applies only to the content in a certain cell, place the notation in that cell. However, if a notation applies to all of the content in a row or column, or to the content in two or more cells, you can use footnotes.
- When writing the text of table footnotes, use the following
- Ensure that all footnotes are written clearly and completely. Use sentences when possible. Avoid cryptic language.
- Ensure that all footnotes have parallel grammatical structure (sentences are paralleled by sentences, phrases by phrases, and so on).
- Place the footnote text at the end of the table, either in a final row that spans the entire table or under the last row in the table.
- Use superscript numbers to indicate the footnotes in the cells to
which they apply. If numbers might be confusing (for example, because
the text in the cells are numerical values), use lowercase letters
- A footnote cited in a column header applies to the entire column.
- A footnote cited in a table cell applies to the text in that cell. Use a cell-level footnote if the note applies to multiple cells in the table.
Attribute or parameter tables in API documents#
When creating attribute or parameter tables in API documents, use the following additional guidelines:
- For tables that describes JSON or XML attributes, write the first sentence of a description with an implied subject. For example, if the attribute is name, the description might be as follows: "Server name, which becomes the initial host name of the server"
- For attributes, include the valid values and default value at the end
of the description. Use the formats "Valid values are n and n."
and "The default is n." For example, "Valid values are
false." and "The default is
- If table descriptions or construction is complex, consider using a definition list or itemized list instead of a table.
- Avoid putting definition lists in tables.
The following table explains the different parts of the preceding URL:
|Part of URL||Explanation|
||The prefix that passes file system requests to the Swift file system.|
The name of the container in Swift that contains the objects to be accessed. Container names must conform to RFC952 restrictions for host names—that is, the characters A-Z, numbers 0-9, and the hyphen (-).
Nonconforming container names are inaccessible by swiftfs.
||A user-friendly "service" name. A service name maps to a collection of configuration entries in the Hadoop core-site.xml file that specify where the container is located (for example, rackspace-dfw).|
||The name of the object or objects in Swift to be referenced. Although
Swift doesn't support paths, swiftfs attempts to interpret names that
look like paths and behave appropriately. For example, an input path
The following table provides the default values for the absolute limits:
|Name||Description||Limit (default value)|
|Node count||Maximum number of allowed data nodes||3|
|Disk||Maximum disk capacity across all data nodes, in gigabytes (GB)||4500|
|RAM||Maximum RAM across all data nodes, in gigabytes (GB)||23040|
|VCPUs||Maximum virtual CPUs across all data nodes||6|
The following matrix indicates which upgrade scenarios are supported:
|Upgrade scenario||Supported||Not supported|
|4.2.0 to 4.2.x||X|
|4.1.x to 4.2.1||X|
|4.1.x to 4.2.0||X|
|4.1.x to 4.1.x||X|
|4.0.0 to 4.2.x||X|
|4.0.0 to 4.1.x||X|
|3 (OpenCenter) to any version||X|
|2 (Alamo) to any version||X|
The following chart compares these top content management systems (CMSs):
|About||Drupal is a powerful, developer-friendly tool for building complex sites. Like most powerful tools, it requires some expertise and experience to operate.||WordPress began as an innovative, easy-to-use blogging platform. With an ever-increasing repertoire of themes, plug-ins, and widgets, this CMS is also widely used for other website formats.|
|Example sites||Community Portal: Fast Company, Team Sugar||
Social Networking: PlayStation Blog
News Publishing: CNN Political Ticker
Education/Research: NASA Ames Research Center
News Publishing:The New York Observer
|Installation||Drupal Installation Forum||WordPress Installation Forum|