# Hack23 Cia Documentation Standards

> Documentation Standards Skill

- Skill: `tomevault-io/hack23-cia-documentation-standards` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/hack23-cia-documentation-standards`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/hack23-cia-documentation-standards/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/hack23-cia-documentation-standards

---


# Documentation Standards Skill

## Purpose
Maintain clear, consistent technical documentation for CIA platform.

## When to Use
- ✅ Writing README files
- ✅ Creating API documentation
- ✅ Documenting architecture
- ✅ Writing user guides

## Markdown Best Practices

### Structure
```markdown
# Title (H1 - only one per document)

## Overview (H2)
Brief description of what this document covers.

## Section 1 (H2)
Content for section 1.

### Subsection 1.1 (H3)
Detailed content.

## References
- [Link 1](url)
- [Link 2](url)
```

### Code Blocks
```markdown
\`\`\`java
public class Example {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
\`\`\`
```

### Tables
```markdown
| Column 1 | Column 2 | Column 3 |
|----------|----------|----------|
| Data 1   | Data 2   | Data 3   |
```

## Documentation Types

### README.md
- Purpose and overview
- Quick start guide
- Installation instructions
- Basic usage examples
- Links to detailed docs

### ARCHITECTURE.md
- System overview
- Component descriptions
- Data flow diagrams
- Technology stack

### API Documentation
```java
/**
 * Retrieves a politician by their personal ID.
 *
 * @param personalId the Swedish personal ID (12 digits)
 * @return the politician if found
 * @throws ResourceNotFoundException if politician not found
 * @throws IllegalArgumentException if personalId format invalid
 */
@GetMapping("/{personalId}")
public Politician getPolitician(@PathVariable String personalId) {
    return service.findById(personalId);
}
```

## Naming Conventions

Files:
- `UPPERCASE_WITH_UNDERSCORES.md` for major docs
- `lowercase-with-hyphens.md` for guides
- `README.md` for module documentation

## Diagrams

Use Mermaid for diagrams:
```markdown
\`\`\`mermaid
graph LR
    A[User] --> B[Web App]
    B --> C[Database]
    B --> D[External API]
\`\`\`
```

## References
- DOCUMENTATION_NAMING_CONVENTION.md
- README.md
- Markdown Guide: https://www.markdownguide.org/

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/hack23) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->