Add documentation on preferring binary enums over booleans

[cmungall]

Summary

This PR adds a comprehensive explanation document to the LinkML schema documentation that advocates for using two-element enumerations instead of boolean types in schema design.

Key Changes

• New document: docs/explanations/binary-enums-vs-booleans.md - A detailed guide explaining why binary enums are preferable to booleans, including:

  • Five key reasons to prefer enums (extensibility, clarity, avoiding cryptic negations, self-documentation, and the "name the scale" pattern)
  • Guidance on when booleans remain acceptable
  • Practical LinkML examples showing binary enum patterns
  • A comparison table summarizing the trade-offs
  • References to the Tidy Design Principles

• Updated navigation: docs/index.md - Added a new "Explanations" section with a link to the binary enums guide

Notable Details

The document draws from established design principles (tidyverse's Tidy Design Principles) and provides concrete examples relevant to LinkML users, including ontology mapping with meaning annotations and practical use cases like sort direction and strand orientation.

https://claude.ai/code/session_012NRY1cEkUdQyExXFvJZUmv

[claude]

Claude finished @cmungall's task —— View job

---

Code Review Analysis

I've completed a comprehensive review of this documentation PR. Overall, this is an excellent addition to the LinkML valuesets project that provides clear guidance on schema design principles.

Todo List:

• Read repository guidelines (CLAUDE.md)
• Review new documentation file
• Review index.md changes
• Analyze content quality and best practices
• Check for technical accuracy
• Provide structured feedback

✅ Strengths

High-Quality Technical Content:

• The document provides clear, well-reasoned arguments backed by established design principles (tidyverse Tidy Design)
• Excellent use of concrete examples that demonstrate abstract concepts
• Strong technical writing that balances accessibility with depth

LinkML Integration:

• Examples properly follow LinkML syntax and conventions
• Appropriate use of meaning annotations for ontology mapping (lines 111, 113, 120, 122)
• Aligns well with repository guidelines for enum naming (CamelCase) and permissible values (UPPERCASE)

Practical Value:

• The extensibility argument (Section 1) is particularly compelling for schema evolution
• The comparison table (lines 154-160) provides an excellent quick reference
• Real-world examples make abstract principles concrete

🔍 Areas for Enhancement

Minor Technical Issues:

1. Ontology Reference Verification (docs/explanations/binary-enums-vs-booleans.md:111-122)

   • The document uses ontology IDs (SIO:001395, SO:0000853, etc.) but per CLAUDE.md guidelines: "ALWAYS check IDs, NEVER guess them. Use OLS to check."
   • Consider adding a note about ID verification or use placeholder examples

2. Consistency in Examples (docs/explanations/binary-enums-vs-booleans.md:126-132)

   • The PresenceStatus enum introduces a third value (NOT_DETERMINED) which somewhat contradicts the "binary enum" concept
   • Consider renaming to "DetectionStatus" or using a purely binary example

Documentation Structure:

• The "When Booleans Are Acceptable" section (lines 92-100) could benefit from LinkML examples to match the pattern established elsewhere
• Consider adding cross-references to other LinkML documentation

🚀 Suggestions

1. Add Validation Command Reference:

   • Since this affects schema design, mention using just validate after implementing changes (per CLAUDE.md guidelines)

2. Consider Migration Guidance:

   • Brief section on how to migrate existing boolean fields to enums without breaking compatibility

3. Link to Repository Examples:

   • Reference existing enums in the valuesets schemas as real-world examples

🔒 Security & Performance

• No security concerns - This is documentation only
• No performance impact - Documentation change only
• No test coverage needed - Documentation files don't require unit tests

📋 Index.md Changes

The changes to docs/index.md are minimal and appropriate:

• Adds new "Explanations" section with proper link
• Follows existing documentation structure
• No issues detected

🎯 Overall Assessment

This PR significantly enhances the project's documentation quality. The binary enums guidance addresses a common schema design challenge with clear, practical advice. The document is well-researched, technically sound, and aligns with established software design principles.

Recommendation: ✅ Approve with minor suggestions

The minor issues noted above don't detract from the overall value of this contribution. This document will serve as an excellent reference for LinkML schema designers.

[Copilot]

Pull request overview

Adds a new “Explanations” document to the LinkML schema docs advocating for two-element enums over booleans, and links it from the docs home page to improve discoverability.

Changes:

• Added a new explanation doc: “Prefer Binary Enums Over Booleans”.
• Updated docs/index.md to include a new “Explanations” section linking to the new doc.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
docs/index.md	Adds an “Explanations” section and links to the new guide.
docs/explanations/binary-enums-vs-booleans.md	New documentation page explaining the rationale and providing LinkML-oriented examples.

[Copilot]

This section is titled “Binary Enum Pattern”, but the PresenceStatus example includes three permissible values (adds NOT_DETERMINED). That’s a good illustration of extensibility, but it’s no longer a binary enum and may confuse readers. Consider moving PresenceStatus into its own “Extending a binary enum” example or renaming the section to reflect that it includes non-binary cases.

[Copilot]

The YAML snippet under “Self-Documenting Code” contains two sample: top-level keys in the same YAML document, which makes the example invalid (the second key overwrites the first). Consider splitting this into two separate code blocks or using distinct keys (e.g., sample1/sample2) so readers can copy/paste valid YAML.

Suggested change

	sample:
	is_control: false
	# Self-explanatory
	sample:
	sample1:
	is_control: false
	# Self-explanatory
	sample2: