Add guidance: when to use inline definitions vs. definition lists vs. tables

[rclee33]

Context

A developer asked for clarity on when to use an inline definition (italicized term defined within a paragraph) versus a definition list. Neither the style guide nor the Confluence training conventions currently provide explicit guidance on choosing between these two approaches, which leads to inconsistent usage across content. Tables are also used to define terms in some cases, but the threshold for choosing a table over the other formats is similarly undocumented.

Proposed guidance

Inline definitions (italicized term in a paragraph)

Use when introducing 1–2 terms within a narrative explanation, where the definition flows naturally in context and the reader does not need to reference it again.

Use when:

• The term only makes sense in the context of the surrounding explanation.
• Extracting the definition into a list would interrupt the reading flow.
• The reader does not need to reference the definition again later in the section.

Example:

The process runs inside a pod, a group of one or more containers that share storage and network resources.

Definition lists:

Use a definition list when introducing three or more related terms together, or when readers are likely to scan or refer back to the definitions.

Use when:

• The terms form a related set (for example, components, roles, modes, or states).
• Each term requires its own multi-sentence explanation.
• The section serves partly as a reference that readers will revisit.

Example:

Pod:: A group of one or more containers that share storage and network resources.
Service:: An abstract way to expose an application running on a set of pods as a network service.
Deployment:: A declaration of the desired state for pods and replica sets.

Tables:

Use when each term requires multiple attributes — for example, name + description + default value, or command + description + example. If a table would only have two columns (term + description), prefer a definition list instead.

Use when:

• Each entry needs more than just a description (for example, type, default, example, or syntax).
• The extra columns provide meaningful information that would be awkward to embed in a definition list.

Example:

[cols="1,2,1"]
|===
| Command | Description | Example

| `oc get`
| List resources of a given type.
| `oc get pods`

| `oc describe`
| Show detailed information about a resource.
| `oc describe pod/my-pod`

| `oc delete`
| Delete a resource.
| `oc delete pod/my-pod`
|===

Threshold summary:

• 1–2 terms, simple definitions: prefer inline definitions
• 3+ related terms, each needing a description: prefer a definition list
• 2 terms that each need multi-sentence definitions: prefer a definition list (length matters as much as count)
• Terms with multiple attributes per entry: prefer a table

Edge cases:

• A single term requiring a lengthy or complex definition (multiple sentences, sub-points) justifies a definition list.
• Terms that appear across separate, unrelated paragraphs should be defined inline rather than collected into a distant list.
• A two-column table (term + description) is usually better as a definition list.

Rationale

The core tradeoff is narrative flow vs. scannability vs. structured data. Inline definitions preserve reading flow, definition lists provide scannability for related sets of terms, and tables add structure when each term carries multiple attributes. Having clear thresholds helps writers make consistent choices.

This guidance could live in the style guide or in the Confluence training conventions — either way, having it documented would help writers make consistent choices.

This issue was developed collaboratively with Claude.

[daobrien]

I think it's a good idea to document how and when to use different writing and presentation tools, such as lists and tables, and especially when ppl start asking about them. What other references did you consult when putting this together? I'd be surprised if IBM had nothing to say, the CSG might have some guidance, and talking to the WN group might expose some ideas as well. You can also tell Claude to consult individual references or "a wide range of references", etc., so that it doesn't default to its usual Google and Microsoft style guides. I also think that whatever we put together would be better in the RHSG and not in confluence.

I'm not sure I agree with your edge cases:

• A single term requiring a lengthy or complex definition (multiple sentences, sub-points) justifies a definition list.
  Multiple sentences, ok. Do defn lists support subpoints?

• Terms that appear across separate, unrelated paragraphs should be defined inline rather than collected into a distant list.
  Why? Can't you have a list of terms defined near the beginning of a topic and then used multiple times throughout the topic?

• A two-column table (term + description) is usually better as a definition list.
  Same question; why? I think this is too broad to generalise. We have literally hundreds of 2-col tables in our content, and obviously enough not all of them fit into the "term + description" category but there's nothing that makes me think they would be better as lists. Perhaps if the definition of "description" were updated this might start to make sense?

[rclee33]

@daobrien Good questions — let me work through each one.

• Sources: The proposal was built primarily from our own content patterns and editorial judgment rather than external references. I'll check what IBM and the CSG say about presentation tool selection and update the proposal with what I find.
• Definition lists and subpoints: I believe that ADOC definition lists do support nested content (additional paragraphs, sublists, admonitions) under a term using list continuation (+). So the edge case is technically supported, although whether it's advisable is worth discussing. Deeply nested definitions can get hard to follow.
• Terms defined at the top of a topic: You're right — that's a valid pattern and the edge case as written rules it out. A list of terms defined near the top of a topic for use throughout is different from collecting unrelated terms scattered across distant sections into one list. I'll revise the edge case to make that distinction clearer.
• Two-column tables: Agreed that the generalization is too broad. The intent was narrower: when a two-column table is specifically term + definition and nothing else, a definition list is usually a better fit because it's the semantic match for that relationship. But that's different from saying all two-column tables should be definition lists. I'll tighten the wording to reflect that.

Edge case 1 (minor wording adjustment):

• Current: A single term requiring a lengthy or complex definition (multiple sentences, sub-points) justifies a definition list.
• Suggested: A single term requiring a lengthy or complex definition (multiple sentences or nested content) justifies a definition list, although deeply nested definitions can be hard to follow. Consider whether the complexity calls for a different approach.

Edge case 2 (substantive revision):

• Current: Terms that appear across separate, unrelated paragraphs should be defined inline rather than collected into a distant list.
• Suggested: A set of related terms defined together near the beginning of a topic for reference throughout is a valid use of a definition list. However, if terms are unrelated to each other and each appears in a different context, define each term inline where it is used rather than collecting them into a single list.

Edge case 3 (narrowed scope):

• Current: A two-column table (term + description) is usually better as a definition list.
• Suggested: When a two-column table consists specifically of a term and its definition, a definition list might be a better semantic fit. Not all two-column tables fall into this category. For example, tables with columns like command + example, or parameter + default value, serve a different purpose.

[daobrien]

• Sources: The proposal was built primarily from our own content patterns and editorial judgment rather than external references. I'll check what IBM and the CSG say about presentation tool selection and update the proposal with what I find.

I think this is a very good idea. Unless we're really sure that our own content contains accurate and consistent examples of what we want to do, and how, I think we should be looking "over the fence" to see what the rest of the world has to say.

• Definition lists and subpoints: I believe that ADOC definition lists do support nested content (additional paragraphs, sublists, admonitions) under a term using list continuation (+). So the edge case is technically supported, although whether it's advisable is worth discussing. Deeply nested definitions can get hard to follow.

Additional paras and admonitions, sure. I wasn't sure about sublists. And even if they are supported, I wouldn't go more than two levels, and yes, consider well how advisable they are.

• Two-column tables: Agreed that the generalization is too broad. The intent was narrower: when a two-column table is specifically term + definition and nothing else, a definition list is usually a better fit because it's the semantic match for that relationship. But that's different from saying all two-column tables should be definition lists. I'll tighten the wording to reflect that.

👍

Edge case 1 (minor wording adjustment):

• Current: A single term requiring a lengthy or complex definition (multiple sentences, sub-points) justifies a definition list.
• Suggested: A single term requiring a lengthy or complex definition (multiple sentences or nested content) justifies a definition list, although deeply nested definitions can be hard to follow. Consider whether the complexity calls for a different approach.

Consider removing "deeply", and I would like us to consider putting a 2-level cap on defn lists. WDYT?

Edge case 2 (substantive revision):

• Current: Terms that appear across separate, unrelated paragraphs should be defined inline rather than collected into a distant list.
• Suggested: A set of related terms defined together near the beginning of a topic for reference throughout is a valid use of a definition list. However, if terms are unrelated to each other and each appears in a different context, define each term inline where it is used rather than collecting them into a single list.

Minor tweak? "However, if those terms are..."

Edge case 3 (narrowed scope):

• Current: A two-column table (term + description) is usually better as a definition list.
• Suggested: When a two-column table consists specifically of a term and its definition, a definition list might be a better semantic fit. Not all two-column tables fall into this category. For example, tables with columns like command + example, or parameter + default value, serve a different purpose.

👍

Thanks for addressing this so promptly.

[rclee33]

Updates with @daobrien's latest feedback. The 2-level cap on def lists that I added below draws on our current language for limiting levels in lists (Section 5.1.1).

[...]

Definition lists:
Use a definition list when introducing three or more related terms together, or when readers are likely to scan or refer back to the definitions. Although definition lists do support nested content (such as sublists or admonitions), try to keep the number of levels to two or fewer.

[..]

Edge case 1 (removed "deeply"):

Current: A single term requiring a lengthy or complex definition (multiple sentences, sub-points) justifies a definition list.
Suggested: A single term requiring a lengthy or complex definition (multiple sentences or nested content) justifies a definition list, although nested definitions can be hard to follow. Consider whether the complexity calls for a different approach.

Edge case 2 (adjusted phrasing):

Current: Terms that appear across separate, unrelated paragraphs should be defined inline rather than collected into a distant list.
Suggested: A set of related terms defined together near the beginning of a topic for reference throughout is a valid use of a definition list. However, if those terms are unrelated to each other and each appears in a different context, define each term inline where it is used rather than collecting them into a single list.
Edge case 3 (narrowed scope):

[rclee33]

I used Claude to check the IBM Style guide (PDF, 432 pages) for guidance on when to use inline definitions, definition lists, or tables for defining terms. Short answer: IBM Style doesn't provide a unified decision framework for choosing between these three formats. The guidance is distributed across separate topics, each covering its own formatting rules without addressing when to choose one over another.

Definition lists (p206): IBM Style says to "use a definition list to describe terms or explain concepts" and provides detailed formatting rules (bold terms, capitalize first letter, consistent style within a list). However, it doesn't address when a definition list is preferable to inline text or a table — it assumes you've already made that choice.

Tables (p223): The Tables topic opens with: "Often, text that is difficult to understand in paragraph form becomes clear in a table format. Tables help highlight relationships among similar pieces of information and are easily scanned for quick reference." This is the closest IBM Style comes to "when to use" guidance for tables, but it's general — not specific to defining terms, and doesn't compare tables to definition lists.

Inline definitions: IBM Style has no named concept of an "inline definition." The closest equivalent appears in word usage entries and the globalization topic. Several word usage entries (pp23, 26, 32) use the pattern "if the term might be unfamiliar to your intended audience, write [full form] on first occurrence" (for terms like "medtech," "fintech," "telco"). The globalization topic (p71) advises: "Define product-specific terms or terms that are used in a special way in a product glossary, or explain them in the text." Neither of these frames inline introduction as a presentation-format decision alongside lists and tables.

One related note on definition lists and LLM consumability (p73): IBM Style's newer LLM guidance flags that "some LLMs do not interpret definition lists as lists and cannot answer questions that require returning the list," and recommends testing whether your LLM can process them. This doesn't affect the style question directly, but it's worth being aware of as a factor in format decisions for content that will be consumed by AI.

Bottom line: The proposed guidance in this issue would fill a gap that exists in IBM Style as well, rather than contradicting it. IBM Style treats these as separate formatting tools, each with its own rules, but doesn't provide thresholds or decision criteria for choosing between them when defining terms.

This issue was researched collaboratively with Claude.

[rclee33]

I used Claude to check the Red Hat Corporate Style Guide, which does not have guidance on definition lists, tables as a presentation-format choice, or when to use inline definitions. Specifically:

• Definition list: "Definition list" does not appear anywhere in the 187-page document.
• Lists (p29-30): The "bulleted lists" entry covers when to use a list ("3 or more items in a series," "providing instructions," "a series would be hard to read in sentence form") and distinguishes bullet, numbered, and lettered lists. But it doesn't mention definition lists or compare lists to tables.
• Tables: The word "table" appears on many pages, but always in the context of product name tables, comparison tables within entries, or references to the IBM Style Guide — never as guidance on when to use a table as a presentation format.
• Inline definitions: No concept of this. The guide does use a pattern of defining terms inline within its own entries (e.g., "A bit (binary digit) is the smallest unit of digital information"), but it doesn't name or prescribe this pattern.

So the corporate style guide is consistent with the findings in IBM Style — neither source provides a decision framework for choosing between inline definitions, definition lists, and tables when defining terms.