# Class Description Quality Rule

## Rule: Write Dictionary-Style Definitions Without Repeating the Class Name

When writing class descriptions, follow these principles:

### 1. No Repetition of Class Name Components

**WRONG:**
```yaml
AcademicArchiveRecordSetType:
  description: >-
    A classification type for archival record sets created by academic
    institutions. This class represents the record set type...
```

**CORRECT:**
```yaml
AcademicArchiveRecordSetType:
  description: >-
    Category for grouping documentary materials accumulated by tertiary
    educational institutions during their administrative, academic, and
    operational activities.
```

The description should define the concept using synonyms and related terms, not repeat words from the class name.

### 2. No Structured Data or Meta-Discussion in Descriptions

Descriptions should contain only the definition. Do not include:
- Alignment explanations (use `broad_mappings`, `close_mappings`, `exact_mappings`)
- Pattern explanations (use `see_also`, `comments`)
- Usage examples (use `examples:` annotation)
- Rationale for mappings (use `comments:` or `annotations:`)

**WRONG:**
```yaml
description: >-
  A type for X. 
  
  **RiC-O Alignment**: Maps to rico:RecordSetType because...
  
  **Pattern**: This is part of a dual-class pattern with Y.
  
  **Examples**: Administrative fonds, student records...
```

**CORRECT:**
```yaml
description: >-
  Category for grouping documentary materials accumulated by tertiary
  educational institutions.

broad_mappings:
  - rico:RecordSetType
see_also:
  - AcademicArchive
examples:
  - value: {...}
    description: Administrative fonds containing governance records
```

### 3. Use Folded Block Scalar (`>-`) for Descriptions

Use `>-` (folded, strip) instead of `|` (literal) to ensure clean paragraph formatting in generated documentation.

**WRONG:**
```yaml
description: |
  A type for X.
  This spans multiple lines.
```

**CORRECT:**
```yaml
description: >-
  A type for X. This will be formatted as a single clean paragraph
  in the generated documentation.
```

### 4. Use LinkML `examples:` Annotation for Examples

Structure examples properly with `value:` and `description:` keys.

```yaml
examples:
- value:
    has_type: hc:ArchiveOrganizationType
    has_label: University Administrative Records
  description: Administrative fonds containing governance records
```

## Summary

| Element | Placement |
|---------|-----------|
| Definition | `description:` (concise, no repetition) |
| Ontology mappings | `exact_mappings`, `broad_mappings`, etc. |
| Related concepts | `see_also:` |
| Usage notes | `comments:` |
| Metadata | `annotations:` |
| Examples | `examples:` with `value` and `description` |