Best practices for including tables

A table is a good way to present descriptions of choices, options, and fields that a user might encounter in a task. You can also use tables for reference information, decision support, compatibility matrices, and choices a user has.

Keep tables as simple as possible, and make sure that screen readers can easily parse tables. For more information about making tables accessible in Splunk docs, see Write accessible documentation.

Here are some best practices for creating effective tables.

Do

• Introduce tables with a full sentence and a colon.
• Always include a header row and include text in all header row cells.
• Capitalize the first letter of every cell entry, unless you're duplicating text from a Splunk product UI and it needs to match for accuracy.
• Use parallel sentence construction in cell entries that belong to the same column. For example, start all entries with verbs, or end all entries with punctuation.
  • If the cell contents are complete sentences, include end punctuation.
  • If the cell contents are characters, words, or phrases, don't include end punctuation.
• Use code samples sparingly in tables.
• You can use tables in a list of task steps.

Don't

• If you include an optional table title, don't include enumeration because the numbers lose context if a table is reused.
• Don't create a table with only 1 row. Consider using a paragraph instead.
• Don't use X or another character to indicate compatibility or support. Instead, use Yes and No. See Spell out words and symbols for more information.
• When possible, don't use lists inside table cells. Keep table content concise.
• Don't merge or split table cells. Use a separate table or a different type of formatting to organize the additional information.
• Don't nest tables within tables. Separate the tables and cross-reference their subheadings if needed.
• Don't leave table cells empty. If you need to keep a cell blank, use a nonbreaking space to make a cell appear blank.
• When possible, don't include links in tables, unless the purpose of the table is to link to cross-references.
• Don't include footnotes in or outside of tables or use a symbol to mimic a footnote. Strive to make your tables as straightforward as possible, so readers don't have to refer to multiple locations to find information.