BMAD-METHOD/expansion-packs/bmad-technical-writing/checklists/glossary-accuracy-checklist.md

Glossary Accuracy Checklist

Use this checklist to ensure the glossary is comprehensive, accurate, and consistent with book content.

Coverage and Completeness

• All technical terms from book are included
• All acronyms are defined and expanded
• Domain-specific jargon is defined
• Framework/library-specific terms included
• Product and tool names defined where needed
• No undefined terms in chapters that should be in glossary

Definition Quality

• Definitions are accurate and factually correct
• Definitions match term usage in book
• Definitions are clear and concise (1-3 sentences)
• Plain language used before technical jargon
• No circular definitions (defining term using itself)
• Context specified (database context vs. general programming)

Consistency

• Terminology consistent throughout book
• Same term always used for same concept
• Spelling variations documented (e.g., "email" vs. "e-mail")
• Capitalization consistent (Boolean vs. boolean)
• Hyphenation consistent (multi-tenant vs. multitenant)
• Singular vs. plural usage consistent

Cross-References

• Related terms cross-referenced
• "See also" entries provided where helpful
• Cross-references accurate (terms actually exist in glossary)
• Broader/narrower term relationships noted
• Alternative terms linked (API vs. Application Programming Interface)

Organization

• Alphabetically sorted correctly
• Case-insensitive alphabetization
• Numbers spelled out ("Two-factor authentication" not "2FA")
• Prefixes (a, an, the) ignored in sorting
• Acronyms alphabetized as single words

Context and Examples

• Usage context provided (chapter reference)
• Code examples included where helpful
• Practical scenarios illustrate meaning
• Examples are accurate and tested
• First-use chapter noted if applicable

First-Use Markers (if required)

• First occurrence of term marked in text (italic, bold)
• Consistent marker style throughout book
• First use per chapter if publisher requires
• Footnotes or parenthetical references if needed

Technical Accuracy

• Definitions verified against authoritative sources
• Current version of technology referenced
• No outdated definitions (old tech versions)
• Industry-standard definitions used where applicable
• Corrections made based on technical review feedback

Target Audience Appropriateness

• Definitions appropriate for reader's skill level
• Beginner-friendly language if target audience is beginners
• Advanced details provided if target audience is experienced
• Prerequisites explained or referenced
• No assumed knowledge beyond target audience

Acronyms and Abbreviations

• All acronyms fully expanded
• Acronym listed with expanded form (e.g., "API (Application Programming Interface)")
• Both acronym and expanded form in glossary if commonly used
• Pronunciation guide if non-obvious
• Common variants noted

Terms vs. Proper Nouns

• Product names capitalized appropriately (Docker, Kubernetes)
• Generic terms vs. brand names distinguished
• Trademarks noted if required
• Open source project names correct (PostgreSQL not "Postgres" if being formal)

Publisher-Specific Requirements

• Format matches publisher style guide
• Length appropriate (typically 3-10 pages)
• Placement correct (appendix, back matter)
• Cross-referenced from index if required
• First-use style matches publisher requirements

Proofreading

• No spelling errors
• No grammatical errors
• Punctuation consistent
• Formatting consistent (bold terms, italic examples, etc.)
• No duplicate entries

Integration with Book

• Glossary terms match usage in chapters
• Definitions consistent with how term is used
• New terms added as chapters are written
• Obsolete terms removed if chapters change
• Version control maintained (glossary updated with revisions)