102 lines
2.7 KiB
Markdown
102 lines
2.7 KiB
Markdown
# 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` |
|