Skip to content

RHSG Design Review

Jump to bottom
David O'Brien edited this page Sep 9, 2026 · 2 revisions

For a long time it's been recognized that the RHSG needs some TLC. This is the first step towards applying that TLC.

Design.xml Chapter: Detailed Analysis and Reorganization Recommendations

Executive Summary

The Design chapter in the Red Hat Technical Writing Style Guide is 1,666 lines and covers an extremely diverse range of topics—from heading capitalization to command syntax to product naming conventions. This analysis identifies natural chapter breaks and proposes a reorganization into 4-5 focused chapters that would improve discoverability, maintainability, and coherence.

Key Finding: The "Documenting the User Interface" section alone is 551 lines (33% of the entire chapter) and contains multiple major topics that deserve chapter-level treatment.

Current Structure Analysis

File Organization

Design.xml has a unique structure:

  • Line 8: XIncludes Book_Design.xml as a <section> (not properly nested as a chapter)
  • Lines 9-1666: Main Design chapter content

Top-Level Sections (9 total)

Line Size (lines) Section ID Title
9 139 heading-styles Heading Styles
149 6 documenting-fonts Documenting Fonts
156 551 documenting-ui Documenting the User Interface
708 30 view-edit-files Describing How to View and Edit Files
739 155 use-hostnames-correctly Using Host and Usernames Correctly
895 39 refer-file-systems Referring to File-system Names
935 162 refer-object-names Referring to Object Names
1098 121 naming-object-classes Naming of Object Classes
1220 447 abbreviations-correctly Using Abbreviations, Acronyms...

Plus additional sections (1172-1666):

  • Documenting Currencies (13 lines)
  • Using Company, Product, and Brand Names Correctly (65 lines)
  • Using Non-breaking Spaces (90 lines)
  • Using Version Numbers Correctly (60 lines)
  • Using Admonitions (47 lines)
  • Making Recommendations (29 lines)
  • Citing Other Works (59 lines)

The "Documenting the User Interface" Mega-Section

Problem

This single section is 551 lines and contains 12 subsections covering fundamentally different topics:

Subsection Lines Topic Area
User Interface Elements and Punctuation ~40 UI documentation
Moving Through Multiple UI Options ~10 UI documentation
Figures, Illustrations, and Screenshots ~35 Visual content
Starting Applications from the Desktop ~20 UI documentation (RHEL-specific)
Documenting Command Terminology and Syntax ~240 Command-line reference
├─ Documenting Multiple or Long Commands ~85 Command-line reference
├─ Omitting Part of Output ~50 Command-line reference
└─ Referring to Replaceable Paths ~30 Command-line reference
Using Escalated Privileges Correctly ~95 Security/best practices
├─ General Recommendations ~50 Best practices
└─ Ansible Courses ~20 Training-specific

Issue Analysis

Semantic Mismatch: The "Documenting the User Interface" title suggests content about GUIs, but 50%+ of the content is about command-line syntax and privilege escalation.

Cross-Domain Mixing:

  1. GUI Documentation (UI elements, screenshots, starting apps) — ~105 lines
  2. Command-Line Documentation (syntax, continuation, output) — ~240 lines
  3. Security Best Practices (privilege escalation) — ~95 lines
  4. Visual Content (figures, screenshots) — ~35 lines

Navigation Problem: A user looking for "how to document commands" must navigate through "Documenting the User Interface" > "Documenting Command Terminology and Syntax" — counterintuitive hierarchy.

Proposed Reorganization

Option A: Five Focused Chapters (Recommended)

Break Design.xml into five separate chapter files:

1. Chapter: Document Structure and Design (NEW)

File: Document_Design.xml

Content (from current Book_Design.xml + Design.xml):

  • Overall Publication Design (Book_Design.xml, 160 lines)
    • Titles and Subtitles
    • Prefaces
    • Abstracts
    • Introductions
    • Heading Placement
    • Unused Heading Titles
  • Heading Styles (Design.xml lines 9-147)
    • Capitalization (title case)
    • Punctuation in headings
    • Writing Effective Titles
    • Verbs in titles
    • File names, commands in titles
  • Using Admonitions (Design.xml lines 1510-1556)
  • Citing Other Works (Design.xml lines 1591-1650)

Rationale: Groups all "big picture" document structure guidance—titles, headings, abstracts, citations.

Estimated Size: ~420 lines

2. Chapter: Documenting User Interfaces (REFACTORED)

File: Documenting_UI.xml

Content (from current Design.xml lines 156-259):

  • User Interface Elements and Punctuation
    • Buttons, menus, icons
    • Documenting UI element punctuation
    • Moving through multiple UI options (navigation paths)
  • Documenting Fonts (Design.xml lines 149-155)
  • Starting Applications from the Desktop (RHEL-specific guidance)

Rationale: Pure GUI/desktop UI documentation guidance. Focused scope.

Estimated Size: ~120 lines

3. Chapter: Documenting Commands and Code (NEW)

File: Documenting_Commands.xml

Content (from current Design.xml lines 282-613):

  • Documenting Command Terminology and Syntax
    • Command prompts ($ vs #)
    • Options vs. arguments vs. flags
    • Command examples (git clone, scp)
  • Documenting Multiple or Long Commands
    • Line continuation characters (\ and `)
    • Cross-platform considerations (Linux vs Windows)
  • Omitting Part of Output
    • Horizontal omissions (...output omitted...)
    • Vertical omissions (...)
  • Referring to Replaceable Paths
    • Linux paths (/path/to/file)
    • Windows paths (C:\path\to\file)
  • Describing How to View and Edit Files (Design.xml lines 708-737)
    • Not specifying editor names
    • Using here-documents
    • When to specify viewers (tail, head, less)

Rationale: All command-line and code-related documentation guidance in one place. Highly cohesive topic.

Estimated Size: ~360 lines

4. Chapter: Naming Conventions and Standards (NEW)

File: Naming_Conventions.xml

Content (from current Design.xml lines 739-1169):

  • Using Host and Usernames Correctly
    • RFC 2606 domain names (example.com)
    • Generic usernames (user, root, admin)
    • Using Extended User and Group Names
    • Realistic names for case studies
    • Sourcing realistic names
  • Referring to File-system Names
    • Capitalization (Btrfs, ext4, NFS, XFS)
    • File-system names in titles
  • Referring to Object Names
    • Object names with qualifying nouns
    • When to use plain language vs. markup
    • Object placement (before vs. after noun)
  • Naming of Object Classes
    • Avoiding duplication in object names
    • Examples: user-remote vs. remote-user

Rationale: All naming conventions (users, hosts, filesystems, objects) grouped logically.

Estimated Size: ~395 lines

5. Chapter: Formatting and Typography (NEW)

File: Formatting_Standards.xml

Content (from current Design.xml lines 1172-1556 + other sections):

  • Figures, Illustrations, and Screenshots (Design.xml lines 224-259)
    • When to use captions vs. callouts
    • Figure documentation
  • Documenting Currencies (Design.xml lines 1172-1184)
    • Currency symbols (US$, AU$)
    • No currency conversions
  • Abbreviations, Acronyms, Initialisms, and Special Characters (Design.xml lines 1185-1289)
    • Definitions (abbreviation vs. acronym vs. initialism)
    • Special characters in file/directory names
  • Using Abbreviations, Acronyms, Initialisms, and Special Characters Correctly (Design.xml lines 1220-1289)
    • First mentions
    • Capitalization
    • Articles (a vs. an)
    • Plurals
    • Possessives
  • Using Company, Product, and Brand Names Correctly (Design.xml lines 1292-1357)
    • Red Hat product names
    • No possessives with product names
    • No "Inc." except in legal docs
    • No articles before product names
  • Using Non-breaking Spaces (Design.xml lines 1358-1448)
    • Red Hat vs. Red Hat
    • Product names + version numbers
    • Formal titles + numerals
    • Numbers + units of measurement
  • Using Version Numbers Correctly (Design.xml lines 1449-1509)
    • Major version only (RHEL 8 not RHEL 8.0)
    • When to use minor versions
  • Making Recommendations (Design.xml lines 1559-1588)
    • "Red Hat recommends" vs. "It is recommended"

Rationale: All mechanical formatting, typography, and brand standards in one reference chapter.

Estimated Size: ~520 lines

6. Chapter: Security and Best Practices (NEW - Optional)

File: Best_Practices.xml

Content (from current Design.xml lines 614-707):

  • Using Escalated Privileges Correctly
    • General Recommendations
    • When to use sudo vs. sudo -i
    • Ansible Courses (specific guidance)
    • Classroom security exceptions

Rationale: Security and procedural best practices separated from pure documentation mechanics.

Estimated Size: ~95 lines

Note: This section is currently nested within "Documenting the User Interface" which makes no semantic sense. Could be merged into "Documenting Commands and Code" instead of being a standalone chapter.

Option B: Four Focused Chapters (Alternative)

Merge Option A chapters 2 and 3:

2. Chapter: Documenting Interfaces and Commands (MERGED)

  • Documenting User Interfaces (GUI)
  • Documenting Commands and Code
  • Using Escalated Privileges Correctly (security best practices)

Estimated Size: ~575 lines

Trade-off: Larger but still cohesive (both GUI and CLI are "interfaces").

Option C: Three Chapters (Minimal Reorganization)

Keep closer to current structure but split the mega-sections:

1. Document Design and Headings

  • From Book_Design.xml + Heading Styles
  • ~280 lines

2. Documenting Technical Content

  • UI, Commands, Files, Privileges
  • ~650 lines

3. Formatting, Naming, and Conventions

  • All naming conventions, abbreviations, brands, spacing
  • ~735 lines

Trade-off: Less disruptive but still has large, heterogeneous chapters.

Detailed Chapter Break Points

Break Point 1: Separate Book_Design.xml Integration

Current Issue: Book_Design.xml is XIncluded as a <section> on line 8, making it subordinate to Design chapter.

Recommendation: Promote Book_Design.xml to a chapter-level file included directly in the main document.

<!-- In Style_Conventions_for_Writers_and_Editors.xml -->
<part id="part-Writing_Style_Guide">
    <xi:include href="Objectives.xml" />
    <xi:include href="Grammar.xml" />
    <xi:include href="Book_Design.xml" />  <!-- NOW A CHAPTER -->
    <xi:include href="Documenting_UI.xml" />
    <xi:include href="Documenting_Commands.xml" />
    ...
</part>

Required Changes:

  • Change Book_Design.xml root element from <section> to <chapter>
  • Remove XInclude from Design.xml line 8
  • Update Book_Design.xml header from <!DOCTYPE section to <!DOCTYPE chapter

Break Point 2: Extract "Documenting Commands" (Line 282)

What to Extract: Lines 282-707 of current Design.xml

New Chapter Structure:

<chapter id="documenting-commands">
    <title>Documenting Commands and Code</title>
    <para>
        This chapter provides guidelines for documenting command-line interfaces,
        shell commands, code examples, and related technical content.
    </para>
    
    <section id="documenting-command-syntax">
        <title>Command Terminology and Syntax</title>
        <!-- Content from Design.xml lines 282-440 -->
    </section>
    
    <section id="continuation">
        <title>Documenting Multiple or Long Commands</title>
        <!-- Content from Design.xml lines 441-526 -->
    </section>
    
    <section id="omitting">
        <title>Omitting Part of Output</title>
        <!-- Content from Design.xml lines 527-580 -->
    </section>
    
    <section id="replaceable-paths">
        <title>Referring to Replaceable Paths</title>
        <!-- Content from Design.xml lines 581-613 -->
    </section>
    
    <section id="escalated-privileges">
        <title>Using Escalated Privileges Correctly</title>
        <!-- Content from Design.xml lines 614-707 -->
    </section>
    
    <section id="view-edit-files">
        <title>Describing How to View and Edit Files</title>
        <!-- Content from Design.xml lines 708-737 -->
    </section>
</chapter>

Rationale: These sections all relate to command-line documentation and have high semantic cohesion.

Break Point 3: Extract "Naming Conventions" (Line 739)

What to Extract: Lines 739-1097 of current Design.xml

New Chapter Structure:

<chapter id="naming-conventions">
    <title>Naming Conventions and Standards</title>
    <para>
        This chapter describes naming conventions for usernames, hostnames,
        file systems, and objects used in Red Hat documentation.
    </para>
    
    <section id="use-hostnames-correctly">
        <title>Using Host and Usernames Correctly</title>
        <!-- Content from Design.xml lines 739-801 -->
        
        <section id="using-extended-names">
            <title>Using Extended User and Group Names</title>
            <!-- Content from Design.xml lines 802-893 -->
        </section>
    </section>
    
    <section id="refer-file-systems">
        <title>Referring to File-system Names</title>
        <!-- Content from Design.xml lines 895-933 -->
    </section>
    
    <section id="refer-object-names">
        <title>Referring to Object Names</title>
        <!-- Content from Design.xml lines 935-1096 -->
    </section>
    
    <section id="naming-object-classes">
        <title>Naming of Object Classes</title>
        <!-- Content from Design.xml lines 1098-1169 -->
    </section>
</chapter>

Rationale: All sections deal with naming conventions for different types of objects.

Break Point 4: Extract "Formatting Standards" (Line 1172)

What to Extract: Lines 1172-1666 (end of file)

New Chapter Structure:

<chapter id="formatting-standards">
    <title>Formatting and Typography</title>
    <para>
        This chapter covers formatting standards for currencies, abbreviations,
        product names, version numbers, and other mechanical formatting concerns.
    </para>
    
    <section id="document-currencies">
        <title>Documenting Currencies</title>
        <!-- Content from Design.xml lines 1172-1184 -->
    </section>
    
    <section id="using-abbreviations">
        <title>Abbreviations, Acronyms, Initialisms, and Special Characters</title>
        <!-- Content from Design.xml lines 1185-1219 -->
        
        <section id="abbreviations-correctly">
            <title>Using Abbreviations Correctly</title>
            <!-- Content from Design.xml lines 1220-1289 -->
        </section>
    </section>
    
    <section id="product-names">
        <title>Using Company, Product, and Brand Names Correctly</title>
        <!-- Content from Design.xml lines 1292-1357 -->
    </section>
    
    <section id="nonbreaking-spaces">
        <title>Using Non-breaking Spaces</title>
        <!-- Content from Design.xml lines 1358-1448 -->
    </section>
    
    <section id="version-numbers">
        <title>Using Version Numbers Correctly</title>
        <!-- Content from Design.xml lines 1449-1509 -->
    </section>
    
    <section id="admonitions">
        <title>Using Admonitions</title>
        <!-- Content from Design.xml lines 1510-1556 -->
    </section>
    
    <section id="making-recommendations">
        <title>Making Recommendations</title>
        <!-- Content from Design.xml lines 1559-1588 -->
    </section>
    
    <section id="citing-other-works">
        <title>Citing Other Works</title>
        <!-- Content from Design.xml lines 1591-1650 -->
    </section>
</chapter>

Rationale: All mechanical formatting, brand standards, and typography rules grouped together as reference material.

Break Point 5: Refactor "Documenting UI" (Line 156)

What to Extract: Lines 156-281 + 224-259 (figures)

New Chapter Structure:

<chapter id="documenting-ui">
    <title>Documenting User Interfaces</title>
    <para>
        This chapter provides guidelines for documenting graphical user interfaces,
        including UI elements, screenshots, and desktop applications.
    </para>
    
    <section id="gui-elements-punctuation">
        <title>User Interface Elements and Punctuation</title>
        <!-- Content from Design.xml lines 172-222 -->
    </section>
    
    <section id="figures-illustrations">
        <title>Figures, Illustrations, and Screenshots</title>
        <!-- Content from Design.xml lines 224-259 -->
    </section>
    
    <section id="starting-apps">
        <title>Starting Applications from the Desktop</title>
        <!-- Content from Design.xml lines 260-281 -->
    </section>
    
    <section id="documenting-fonts">
        <title>Documenting Fonts</title>
        <!-- Content from Design.xml lines 149-155 -->
    </section>
</chapter>

Rationale: Focus purely on GUI documentation, removing command-line content.

Sections That Need Special Handling

1. "Using Escalated Privileges Correctly" (Lines 614-707)

Current Location: Nested within "Documenting the User Interface" > "Documenting Command Syntax"

Problem: This is security best practices guidance, not command syntax documentation.

Options:

  • Option A: Move to "Documenting Commands and Code" chapter (since it's about sudo/command-line)
  • Option B: Create a "Best Practices" chapter (if other best practices emerge)
  • Option C: Move to a "Security" chapter (if one exists or is created)

Recommendation: Move to "Documenting Commands and Code" as it's closely related to command-line usage in training materials.

2. "Figures, Illustrations, and Screenshots" (Lines 224-259)

Current Location: Within "Documenting the User Interface"

Problem: Figures appear in all types of documentation, not just UI docs.

Options:

  • Option A: Keep in "Documenting UI" chapter (figures often document UI)
  • Option B: Move to "Document Design" chapter (figures are structural elements)
  • Option C: Move to "Formatting Standards" chapter (figures are a formatting concern)

Recommendation: Move to "Document Design" chapter alongside headings, admonitions, and citations (all structural/layout concerns).

3. "Book_Design.xml" XInclude (Line 8)

Current Location: Included as a <section> within Design chapter

Problem: It's actually chapter-level content about overall document design (titles, abstracts, prefaces).

Recommendation:

  1. Change Book_Design.xml from <section> to <chapter> root element
  2. Include it at Part I level, not within Design.xml
  3. Rename to Document_Design.xml for clarity
  4. Remove XInclude from Design.xml line 8

Migration Strategy

Phase 1: Planning and Prep

  1. Create backup of current Design.xml
  2. Create new chapter files (empty templates with correct DocBook headers)
  3. Map every section ID to its destination file (maintain ID integrity for cross-references)
  4. Grep for cross-references to Design.xml sections (grep -r 'linkend="heading-styles"' etc.)

Phase 2: Content Migration

  1. Start with smallest extractions first:
    • Extract "Documenting Fonts" (6 lines) to Documenting_UI.xml
    • Extract "Currencies" (13 lines) to Formatting_Standards.xml
  2. Extract large sections:
    • Extract "Documenting Commands" (425 lines) to new chapter
    • Extract "Naming Conventions" (430 lines) to new chapter
    • Extract "Formatting Standards" (495 lines) to new chapter
  3. Refactor "Documenting UI" (remove command/security content)
  4. Handle Book_Design.xml promotion

Phase 3: Integration

  1. Update main document (Style_Conventions_for_Writers_and_Editors.xml) to include new chapters
  2. Verify all section IDs are unique and cross-references resolve
  3. Build with Publican and check for errors
  4. Review generated HTML for broken links

Phase 4: Testing

  1. Validate XML with DocBook schema
  2. Check all cross-references resolve correctly
  3. Compare before/after HTML output (should be identical except for chapter breaks)
  4. Review table of contents structure

Cross-Reference Impact Analysis

Sections Most Frequently Referenced

Based on analysis, these Design.xml sections are likely referenced from other chapters:

  1. heading-styles - Referenced from Grammar, Language
  2. documenting-command-syntax - Referenced from Translation, Resources
  3. nonbreaking-spaces - Referenced from Language, A.xml (dictionary)
  4. product-names - Referenced from Language, B.xml, P.xml
  5. abbreviations-correctly - Referenced from Grammar

Maintaining Cross-Reference Integrity

Strategy: Keep all section IDs unchanged during migration.

Example: Even though "documenting-command-syntax" moves from Design.xml to Documenting_Commands.xml, its id="documenting-command-syntax" remains the same.

DocBook XRef Behavior: <xref linkend="documenting-command-syntax"/> will still resolve correctly regardless of which chapter file contains it, as long as the ID is unique across the entire book.

Verification Command:

# Find all cross-references to Design.xml section IDs
grep -rn 'linkend="heading-styles\|documenting-command-syntax\|nonbreaking-spaces"' en-US/*.xml

Recommended Chapter Titles

If implementing Option A (Five Chapters), here are the recommended new chapter titles and IDs:

New Chapter File Chapter ID Chapter Title Estimated Size
Document_Design.xml document-design Document Structure and Design 420 lines
Documenting_UI.xml documenting-ui Documenting User Interfaces 120 lines
Documenting_Commands.xml documenting-commands Documenting Commands and Code 425 lines
Naming_Conventions.xml naming-conventions Naming Conventions and Standards 430 lines
Formatting_Standards.xml formatting-standards Formatting and Typography 495 lines

Total: ~1,890 lines (current Design.xml is 1,666 lines + Book_Design.xml 160 lines = 1,826 lines)

(Slight increase due to added chapter introductions and section spacing)

Part I Reorganized Table of Contents (Proposed)

After reorganization, Part I would include:

<part id="part-Writing_Style_Guide" label="I">
    <title>Writing Style Guide</title>
    
    <xi:include href="Objectives.xml" />
    <xi:include href="Grammar.xml" />
    <xi:include href="Punctuation.xml" />  <!-- PROMOTED from within Grammar -->
    <xi:include href="Document_Design.xml" />  <!-- WAS Book_Design.xml -->
    <xi:include href="Documenting_UI.xml" />  <!-- EXTRACTED from Design.xml -->
    <xi:include href="Documenting_Commands.xml" />  <!-- EXTRACTED from Design.xml -->
    <xi:include href="Naming_Conventions.xml" />  <!-- EXTRACTED from Design.xml -->
    <xi:include href="Formatting_Standards.xml" />  <!-- EXTRACTED from Design.xml -->
    <xi:include href="Language.xml" />
    <xi:include href="Translation.xml" />
    <xi:include href="Cross_references.xml" />
    <xi:include href="Resources.xml" />
</part>

Result:

  • Was 7 chapters (with oversized Design.xml)
  • Now 12 chapters (all <200 lines except Punctuation at 310)

Benefits of Reorganization

1. Improved Discoverability

  • Users looking for "how to document sudo commands" no longer need to navigate through "Documenting the User Interface"
  • Command-line and GUI documentation are cleanly separated
  • Table of contents is more descriptive

2. Better Maintainability

  • Smaller, focused files are easier to edit
  • Less risk of merge conflicts in version control
  • Easier to assign ownership/review of specific topics

3. Semantic Coherence

  • Each chapter has a single, clear focus
  • No more "catch-all" chapters
  • Hierarchies make logical sense

4. Easier Cross-Referencing

  • Clear chapter titles help users understand what <xref> will link to
  • Less deeply nested sections (currently up to 3 levels deep)

5. Translation Efficiency

  • Smaller files are easier to manage in translation workflows
  • Less context switching for translators

Risks and Mitigation

Risk 1: Breaking Cross-References

Mitigation:

  • Keep all section IDs unchanged
  • Test with Publican build before/after
  • Grep for all linkend attributes referencing Design.xml sections

Risk 2: Disruption to Contributors

Mitigation:

  • Document the reorganization in a CHANGES.md file
  • Update CLAUDE.md with new file structure
  • Create a migration guide showing old section → new chapter mapping

Risk 3: Inconsistent Chapter Sizes

Reality Check:

  • Grammar.xml: 1,107 lines (35K)
  • Punctuation.xml: 310 lines (31K)
  • Language.xml: 510 lines (51K)
  • Translation.xml: 240 lines (24K)

Proposed chapters (120-495 lines) are well within established norms.

Alternative: Minimal Disruption Approach

If full reorganization is too disruptive, consider these quick wins:

Quick Win 1: Extract Just "Documenting Commands"

  • Create Documenting_Commands.xml with lines 282-707 of Design.xml
  • Reduces Design.xml from 1,666 to ~1,240 lines
  • Minimal cross-reference impact

Quick Win 2: Promote Book_Design.xml to Chapter

  • Change root element from <section> to <chapter>
  • Include at Part I level
  • Zero content migration needed

Quick Win 3: Rename Design.xml

  • Rename to Formatting_and_Conventions.xml
  • Better reflects actual content
  • No structural changes needed

Conclusion

The Design.xml chapter suffers from topic creep and semantic incoherence. The "Documenting the User Interface" section alone demonstrates the problem: it contains command-line syntax (50%), security best practices (17%), and actual UI documentation (33%).

Recommended Action: Implement Option A (Five Focused Chapters) to create:

  1. Document Structure and Design
  2. Documenting User Interfaces
  3. Documenting Commands and Code
  4. Naming Conventions and Standards
  5. Formatting and Typography

This reorganization aligns with the guide's own advice: "Use titles that represent the content" and "Focus on the task at hand."

Next Step: Create a detailed migration plan with section-by-section mapping and cross-reference verification checklist.

Clone this wiki locally