| name | documentation-standards |
| description | Write clear technical documentation: Markdown best practices, diagrams, API docs per DOCUMENTATION_NAMING_CONVENTION.md |
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
# 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
\`\`\`java
public class Example {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
\`\`\`
Tables
| 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
@GetMapping("/{personalId}")
public Politician getPolitician(@PathVariable String personalId) {
return service.findById(personalId);
}
Naming Conventions
Files:
UPPERCASE_WITH_UNDERSCORES.md for major docslowercase-with-hyphens.md for guidesREADME.md for module documentation
Diagrams
Use Mermaid for diagrams:
\`\`\`mermaid
graph LR
A[User] --> B[Web App]
B --> C[Database]
B --> D[External API]
\`\`\`
References
