# From tables to layers: progressive disclosure in a documentation table Tables are great for enhancing scannability: readers can easily browse rows in the first column and access the information they're looking for in relevant cells of the corresponding row. However, tables display every column in front of every reader, whatever their needs, at once. This contradicts a major principle of information architecture and design: layering, or progressive disclosure, which information-design researcher David Farkas dubbed a ["safety net"](https://direct.mit.edu/books/edited-volume/2438/chapter-abstract/64685/Layering-as-a-Safety-Net-for-Minimalist?redirectedFrom=fulltext) for minimalist documentation. (An earlier article, [Less is more](https://redaction-technique.org/less-is-more-layering), comes at the same idea from the psychology side.) With modern web frameworks, tech writers can now allow users to display or hide table columns or sort rows based on different criteria. On my documentation site, for example, you can sort the rows of the [API endpoints](https://docs.redaction-technique.org/en/about-the-api/#endpoints), [target formats](https://docs.redaction-technique.org/en/about-this-blog/#target-formats), and [manual layout options](https://docs.redaction-technique.org/en/tech-writing-process/source-format/#key-principles) tables alphabetically, then restore their original order. This article illustrates how to sort rows and hide columns in a live 1978 NBS table. ## Why tables overwhelm One table is carrying too many jobs. Every reader gets every column, whatever question they came with. ### Everything at once A table has no reading order of its own. Every cell has the same weight: the column that answers the reader's question looks exactly like the three that qualify it. So the reader does the sorting, every time, for every table. Which column matters? Which ones can wait? A writer who knows the answer and doesn't act on it leaves that work to each reader separately. The usual minimalist fix is to cut the columns that most readers don't need. That makes the table easier to read and useless to the reader who needed exactly the column that got cut. ### The NBS table For example, here is a table showing how 50 studies compared software processing times.
Table 4.1. How processing times were reported
Reported? Central tendency (mean or median) Standard deviation Individual problems discussed Worst case analysis
No 36 47 26 48
Yes 14 3 24 2
The table requires users to: * Find the row that matches their question, **Yes** or **No**. * Pick the one column that answers it. * Ignore the three that don't. * Keep enough context in their short-term memory to read the number correctly. But columns aren't equally important to every reader. Someone who wants to know whether these studies reported an average at all needs one column: 14 did, 36 didn't. Someone checking how rigorous the reporting was needs the other three. ## Progressive disclosure Reveal information in the order readers need it. Nothing is removed: the rest stays labeled, visible in the control, and one selection away. ### Layering The first two layers live in the table. The view options run in the same order: 1. **Central tendency** 2. **Supporting measures** 3. **All columns** ### Disclosure vs. hiding Can a reader who has never seen the page find everything? The control shows which view is on, and users can always select to view **All columns**.
### Choosing a mechanism Three mechanisms cover most layered documentation. They aren't interchangeable:
Use `
` when the extra material is optional and makes sense on its own. Use tabs when the alternatives exclude each other and nobody needs to compare them. Use view options when one table serves several readers who may still want to compare across views, as with the NBS table, or with [A practical comparison of information types](https://docs.redaction-technique.org/en/toolkit/information-types/#a-practical-comparison), which opens a comparison of Markdown, DITA, and OpenAPI on an overview and keeps typing and validation one selection away. ## Implementation ### Markup for layers The table is a single ``, wrapped in the `TableViews` component, and each view is only a list of column IDs. **MDX: the three views of the NBS table** ```js views={[ { id: "central-tendency", label: "Central tendency", columns: ["central-tendency"] }, { id: "supporting", label: "Supporting measures", columns: ["standard-deviation", "individual-problems", "worst-case"] }, { id: "all", label: "All columns", columns: ["central-tendency", "standard-deviation", "individual-problems", "worst-case"] }, ]} ``` The order of the list is the order of the layers. Choosing a view sets the native `hidden` attribute on the cells of the columns it doesn't show. The first column always stays, since it names the rows. Nothing is copied, so no view can drift out of sync with the others. Most readers can skip a `
` element, which the browser renders collapsed under its ``. **HTML: collapsed state** ```html
What the counts mean

Each cell counts papers out of all 50…

``` **HTML: expanded state** ```html
What the counts mean

Each cell counts papers out of all 50…

``` ### Example: an API comparison Let's take another example: a table comparing REST, GraphQL, and gRPC across six criteria. Options are columns. Criteria are rows, so the layers are rows. What goes first depends on the question the reader brings. Layered for someone choosing an approach, the typical use row comes first: | | REST API | GraphQL | gRPC | | ----------- | -------- | --------------------- | -------------------------------- | | Typical use | Web APIs | Flexible data queries | Service-to-service communication |
Client control and streaming | | REST API | GraphQL | gRPC | | ---------------------- | ---------- | --------- | ------------------ | | Client controls fields | Usually no | Yes | Defined by service | | Streaming | Limited | Supported | Strong support |
Representation, transport, and data format | | REST API | GraphQL | gRPC | | ---------------------- | --------- | ------- | ---------------- | | Primary representation | Resources | Graph | Services | | Transport | HTTP | HTTP | HTTP/2 | | Data format | JSON | JSON | Protocol Buffers |
What changes is which rows the reader meets first. ### Before you layer a table Run through these questions before you publish: * Does the first view answer the question most readers bring? * Is everything outside the first view genuinely secondary, and does the text say why the first layer is first? * Do the views run from the first layer to everything, with everything always offered? * Does every view keep the row labels, so no value appears without its context? * Does the control show which view is on? * Without JavaScript, does the reader get the full table? * Can the reader switch views with the keyboard? * Would a `
` block or tabs be simpler than views on one table? ## Key takeaway Progressive disclosure doesn't remove information. It decides the order readers meet it in: the column most of them came for first, everything else one labeled selection away. *Hero image: ["Layers"](https://www.flickr.com/photos/snowpeak/12547422744/) by [John Fowler](https://www.flickr.com/photos/snowpeak/), licensed under [CC BY 2.0](https://creativecommons.org/licenses/by/2.0/).* --- Source: https://redaction-technique.org/from-tables-to-layers-responsive-stacking