From 71426040e6c06c333df0bc0391a2756e41655c18 Mon Sep 17 00:00:00 2001
From: Annie Streater <12902836+streats@users.noreply.github.com>
Date: Tue, 31 Jan 2023 21:10:53 +0000
Subject: [PATCH] Updated section on Tables (#34282)

Co-authored-by: Laura Coursen <lecoursen@github.com>
Co-authored-by: Ethan Palm <56270045+ethanpalm@users.noreply.github.com>
---
 contributing/content-style-guide.md | 29 +++++++++++++++++++++++++++++
 1 file changed, 29 insertions(+)

diff --git a/contributing/content-style-guide.md b/contributing/content-style-guide.md
index 6c4460d9f2..91ac456fb8 100644
--- a/contributing/content-style-guide.md
+++ b/contributing/content-style-guide.md
@@ -562,10 +562,39 @@ Use reusable strings for individual nouns (e.g. product names) or for complete s
 
 ## Tables
 
+### Use tables only for presenting tabular information
+Tables work best for presenting tabular data, such as information that needs to be compared or values with multiple attributes. Do not use tables for simple lists - see the "[Lists](https://github.com/github/docs/blob/main/contributing/content-style-guide.md#lists)" section of this document. 
+
+### Avoid describing tables
 A table’s contents should be clear from the preceding content - avoid unneeded descriptions. If you must describe a table, use complete sentences closed with a period.
 - **Use:** Nothing or a clear header.
 - **Avoid:** “The table below shows what kind of migration data is exported:”
 
+### Include a value for every cell
+Every cell in a table must contain a value. If there is no data, use "None" or "Not applicable". Do not use "NA" or "N/A".
+
+### Use clear, consistent symbols and labels
+
+For tables that use symbols:
+
+* Populate all cells. For example in a permissions table, do not mark only the cells for things that require a permission.
+* Use [octicons](https://github.com/github/docs/blob/main/contributing/content-markup-reference.md#octicons) or SVG. Do not use emoji. 
+* Use a [check mark](https://primer.style/octicons/check-16) for affirmative values ("Yes", "Required", "Supported") and a [cross](https://primer.style/octicons/x-16) for negative values ("No", "Optional", "Unsupported").
+* Use `aria-label` to describe the meaning of the symbol, not its visual characteristics. For example, "Required", not "Check mark icon".
+
+Where table data is not truly binary (every value is either "Yes" or "No", for example), text values may be needed in addition to, or instead of, symbols. For example on the page "[About GitHub Support](https://docs.github.com/en/support/learning-about-github-support/about-github-support)", some features are marked as "Available to purchase". 
+
+### Use footnotes sparingly
+Avoid using footnotes where possible. Consider instead whether you could place a [callout](https://github.com/github/docs/blob/main/contributing/content-style-guide.md#callouts) before or after the table, or present the information in another way. See some [examples of alternatives to footnotes from NICE.org.uk](https://www.nice.org.uk/corporate/ecd6/chapter/footnotes).
+
+If you must use footnotes:
+
+* Use numbers. Do not use typographical symbols or special characters.
+* Link the footnote number to the explanation. The explanation should receive focus (with a focus indicator) when clicking on the footnote number.
+* Ideally, include a back link in the footnote explanation so users can return to the original context - this may be difficult if the footnote is used in multiple places.
+
+Markdown on GitHub does not have built-in support for linking footnotes in this way, so you would need to find another solution.
+
 ## Titles
 
 Use quotation marks around article titles, whether the article is hosted on GitHub Docs or elsewhere. Do not include quotation marks around the names of external sites.