March 2019

Tables Must Die!

CIDMIconNewsletterLarry Kollar, ARRIS

As tablet computing grows in popularity, customers will continue shifting from reading documentation on large computer screens or paper, to reading on tablets, eReaders, or smartphones. This requires us to re-think how we present certain information, especially tables, to accommodate upcoming customer needs.

Examples in this paper are taken from working documentation. In general, this paper is long on describing problems, and short on concrete solutions. There is no “one size fits all” solution to the problem, as different tables are likely to require different reworking.

Use, Misuse, and Outright Abuse

Tables were originally a compact way to present related pieces of information in a two-dimensional format. Its compact form allows readers to quickly scan the table to find what is needed.

Unfortunately, the simple, compact layout invites misuse. Information that should be items in a list become table rows, all too often. DITA is not immune, with its abominable rendering of definition lists (<dl>) as tables for PDF. Technical writers converting large documentation bases to DITA often are pressed for time and bring tables over as tables, not considering whether the content in some of those tables could be modeled differently.

Perhaps the most egregious examples of table abuse can be found in HTML (and some word processor) layouts, where the designer uses tables to layout information in discrete columns. Early examples of Information Mapping®, from ca. 1990, are another example.

General Issues

Garrish and Gylling describe the problem with large tables in eBook readers, and the inadequacy of one common workaround:

The complex nature of tables relative to limited rendering area of typical reading systems has led to the worse practice of excluding the data in favor of images of the table… The motivating hope behind this practice seems to be that images will take away rendering issues on small screens, but don’t fall into this trap.

The Mobipocket Developer Center is more blunt:

The user experience becomes worse as the table size grows. You should therefore avoid large tables. If you encounter a table that covers a whole paper page, or a table that contains a lot of text in one cell, you are basically in front of a non-reflowable layout… creative action has to be taken to redesign the table as something else that is reflowable. (emphasis in original)

What To Do?

If you are truly interested in making your documentation accessible on the widest number of devices, then… tables must die.

Sooner or later, authors using DITA (or any other kind of semantic markup) need to examine topics to determine whether their markup is semantic or presentational. Some tables may be best kept intact, but others likely should be tagged in some other way. In some cases, specializations may be needed.

All too often, tables could have been lists. Some tables are easy to refactor as lists, while others might need more effort. Examples follow.

Example 1: Reformatting Long Tables

The question is, what kind of list? The answer requires A long, 2-column table can easily be reformatted as a list. The results reflow well, and make good use of screen real estate, without the text becoming too dense.

The question is, what kind of list? The answer requires analyzing the information.

In the following table, we have a bitmap variable, describing the function of each bit. Is this:

  • a parameter list? (each bit is part of a variable)
  • a definition list? (we are defining the function for each bit)
  • something else? (many similar tables might indicate the need for a specialization, perhaps called bitmap)

In the actual documentation, this table runs several pages. I have shortened it here (Table 1).

For this example, we can rebuild the information as a parameter list (parml). Note the “Bit” in the hanging part of each list item. Labeling standalone numeric items is important to prevent readers from forgetting what the numbers mean. We also moved the name of the bit function to the “term” part of the parameter list.

Bit 0x00000001: Disable NCS Piggyback Messages (NCS only)

Set this bit to disable transmission of NCS piggybacked messages (that is, sending more than one NCS message in a UDP packet). This may be required by Call Agents that do not properly handle piggybacked NCS messages.

Note: NCS redirection may not function properly when piggybacked messages are disabled.

Bit 0x00000002: Prevent Endpoint Lockstep Quarantine Mode (NCS only)

Set this bit to prevent endpoints from entering the lockstep quarantine mode. This may be required by Call Agents that leave the endpoint in lockstep mode.

When this bit is clear, the gateway must receive a new Notification Request command after sending a Notify command. Until this happens, the endpoint is in a lockstep state, and events that occur and are to be detected are simply stored in the quarantine buffer until receiving the Notification Request command.

Bit 0x00000004: Show OOS instead of Idle for unprovisioned lines
Set this bit to return oos(0) instead of idle(1) in the arrisMtaDevLineCardState object for unprovisioned lines.

Bit 0x00000008: T.38 Capability Descriptor (NCS only)
Set this bit to reduce the SDP capability descriptor to only send T.38-related information.

Reformatting Wide Tables

Wide tables can be further broken down into sub-categories:

  • A relatively small number of columns, typically three or four, with large blocks of text in each cell.
  • Four or more cells per row (perhaps a dozen or more), with short (often numeric) text.
  • A combination of the two. Usually, only one or two columns have large blocks of text.

Each type of wide table requires a different approach for reformatting. Turning the table sideways (i.e. switching rows and columns) may not be viable, as the wide table then becomes a long table.

Example 2a: Large Text Blocks
The following table shows failure types in a diagnostics test, along with cause, symptoms, and normal results. (See Table 2).

Again, this is a list in table form—a list of failure modes with some extra data. Each item has more than two pieces of information, though, and failure modes are not parameters, so a parameter list might not be the best solution.

One point of interest: the two most closely-related items (failure mode and normal result) are on opposite ends of each row. If we re-format the table as a bulleted list, we can put those two items together:

Example 2b: Many Columns
This table has five columns, with little information in each cell, plus a “notes” block. The reformatted version, with some annotation, follows.

The key to dealing with a table like this is to understand what it’s trying to say. In this case, the firmware sets the value of a read-only object based on the values of two other objects and the signaling type. This table could be made narrower by hyphenating the names of the MIB objects in the first two column headings. Or, use a bullet list and a stem sentence to eliminate the table altogether, as shown below.

The value of arrisMtaDevLineRTCPXR depends on the setting of arrisMtaDevVqmEnableRemote, as follows:

  • normal(0): RTCP-XR is disabled, except for PC20 loads when pktcEDVACodecRTCPXR is set to true(1). However, NCS and ARRIS SIP loads honor requests from the Call Agent or remote, respectively, for RTCP-XR metrics.
  • forceDisable(1): RTCP-XR is always disabled.
  • forceEnable(2): RTCP-XR is always enabled.

Example 3: Wide and Long Tables

The following table describes TR-181 management objects. It has both wide columns, and varying amounts of text in each cell. Discussion and a reformatted version follows.

The Group and Parameter columns could be combined, and the fourth column eliminated, but reflow issues would still be a problem. However, combining the group and parameter, then turning the table into an unordered list, produces the following. It has the advantage of being able to add definitions for each object, something missing from the original table.

Some closing thoughts

In many ways, tables are a kind of list. With some analysis and thought, you can present the data in a list format that allows for reflow and pagination. Tabular presentation works well in PDF on large displays (including tablets), but not so well on smaller displays.

Content such as log messages and management objects might benefit from specialization. Capture and tag the content, then figure out how best to present it under different circumstances. CIDMIconNewsletter