markitect-main/examples/terminology/README.md

# Terminology Document Example

This example demonstrates how to use MarkiTect schemas to validate terminology and glossary documents.

## Overview

Terminology documents (glossaries, dictionaries, lexicons) benefit from consistent structure and validation. This example shows how to:

1. Structure terminology documents with clear categories and term definitions
2. Validate terminology documents using JSON schemas
3. Use MarkiTect's schema extensions for content control

## Files

- **terminology-example.md** - Example terminology document with proper structure
- **terminology-schema.json** - JSON schema for validating terminology documents
- **README.md** - This file

## Terminology Document Structure

A well-structured terminology document includes:

### Required Elements

1. **Main Title (Level 1 Heading)**
   - Should include keywords: "Terminology", "Glossary", "Terms", or "Definitions"

2. **Category Sections (Level 2 Headings)**
   - Organize terms into logical groups
   - Examples: "Core Concepts", "Document Types", "Process Terms"

3. **Term Definitions (Level 3 Headings)**
   - Each term as a level 3 heading
   - Followed by structured content

### Term Structure

Each term should include:

**Required:**
- **Definition:** Clear, concise explanation of the term

**Optional (but recommended):**
- **Synonyms:** Alternative names or abbreviations
- **Related Terms:** Links to related concepts
- **Example:** Practical usage example
- **Use Cases:** Common scenarios
- **Format:** For document type terms
- **Components:** For complex concepts
- **Steps:** For process terms

## Usage

### Using the Registered Schema

The terminology schema is registered in markitect's database and can be used by name:

```bash
# List all registered schemas (terminology-schema.json should appear)
markitect schema-list

# Validate using the registered schema
markitect validate my-glossary.md --schema terminology-schema.json

# Or use the local file directly
markitect validate my-glossary.md --schema examples/terminology/terminology-schema.json
```

### Validate with Detailed Errors

```bash
markitect validate my-glossary.md --schema terminology-schema.json --detailed-errors
```

### Register the Schema (if needed)

If the schema isn't already registered, you can add it to markitect's database:

```bash
markitect schema-ingest markitect/schemas/terminology-schema.json
```

### Generate Schema from Example

```bash
markitect schema-generate terminology-example.md --output my-terminology-schema.json
```

## Schema Features

This schema demonstrates several MarkiTect features:

### 1. Structural Validation

- Enforces consistent heading hierarchy (H1 → H2 → H3)
- Validates minimum term count
- Ensures proper document structure

### 2. Content Pattern Validation

- Validates title pattern (must contain terminology-related keywords)
- Checks for required field labels (Definition:, Synonyms:, etc.)
- Enforces consistent formatting

### 3. MarkiTect Extensions

The schema uses MarkiTect-specific extensions:

#### `x-markitect-sections`
Defines section classifications and requirements:
- `document_title` (required)
- `category_sections` (required, min 1)
- `term_definitions` (required, min 1)

#### `x-markitect-content-control`
Specifies content requirements:
- Required vs optional components
- Content quality metrics (word counts)
- Content instructions for authors

#### `x-markitect-validation-rules`
Custom validation rules:
- Minimum term count (3 required, 10+ recommended)
- Category balance (min 2 terms per category)
- Definition quality checks
- Consistency validation

## Best Practices

### 1. Use Consistent Field Labels

Always use the same labels for metadata:
```markdown
**Definition:** ...
**Synonyms:** ...
**Related Terms:** ...
```

### 2. Write Clear Definitions

- Start with the term's primary meaning
- Use 10-200 words
- Be self-contained (don't require reading other terms)
- Avoid circular definitions

### 3. Group Related Terms

Organize terms into logical categories:
- Core Concepts
- Document Types
- Process Terms
- Quality Attributes
- Deprecated Terms

### 4. Include Examples

Add practical examples for complex terms:
```markdown
**Example:**
\`\`\`markdown
# Heading
Paragraph text
\`\`\`
```

### 5. Link Related Terms

Use **Related Terms:** to create a terminology graph:
```markdown
**Related Terms:** Parser, Token, Node
```

## Extending the Schema

You can customize the schema for your project:

### Add Custom Field Labels

Extend the `bold_text` enum:
```json
"enum": [
  "Definition:",
  "Synonyms:",
  "Your Custom Label:"
]
```

### Adjust Quality Metrics

Modify content quality requirements:
```json
"content_quality": {
  "min_words_per_definition": 20,
  "max_words_per_definition": 300,
  "readability_target": "business"
}
```

### Add Domain-Specific Validation

Include specialized validation rules:
```json
"x-markitect-validation-rules": {
  "domain_specific": {
    "require_acronym_expansion": true,
    "require_source_citations": true
  }
}
```

## Use Cases

### Documentation Projects

- Software project glossaries
- API terminology reference
- Architecture decision records (ADR) glossary
- Domain-driven design (DDD) ubiquitous language

### Technical Writing

- Standards documentation
- Compliance documentation (ISO, SOC2)
- Technical specifications
- Research papers

### Knowledge Management

- Company wikis
- Team handbooks
- Onboarding documentation
- Training materials

## Integration with CI/CD

### Pre-commit Hook

```bash
#!/bin/bash
# .git/hooks/pre-commit
markitect validate docs/glossary.md --schema schemas/terminology-schema.json
```

### GitHub Actions

```yaml
name: Validate Terminology
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install MarkiTect
        run: pip install markitect
      - name: Validate Glossary
        run: |
          markitect validate docs/glossary.md \
            --schema schemas/terminology-schema.json \
            --detailed-errors
```

## Related Examples

- **manpages/** - Manual page documentation validation
- **templates/** - Document template examples
- **design-patterns/** - Software pattern documentation

## Learn More

- [Schema Extensions Specification](../../docs/specifications/schema-extensions-spec.md)
- [MarkiTect Documentation](../../README.md)
- [JSON Schema Documentation](https://json-schema.org/)

## Contributing

To improve this example:

1. Add more terms to demonstrate edge cases
2. Enhance the schema with additional validation rules
3. Create alternative terminology document styles
4. Add multilingual terminology examples

## License

This example is part of the MarkiTect project and follows the same license.