Documentation Standards

📝 Documentation Standards Skill

Strategic Principle: Great documentation is as important as great code. Document for clarity, maintainability, and knowledge transfer.

🎯 Purpose

Enforce consistent documentation standards across Black Trigram, ensuring code, APIs, architecture, and user guides are well-documented with bilingual Korean-English support.

Reference: Hack23 ISMS Secure Development Policy

Enforcement Rules

Rule 1: JSDoc/TSDoc for Public APIs

IF (exported function, class, interface, or type)
THEN (add JSDoc with @param, @returns, @throws, @example)
ELSE (reject - undocumented public APIs impede maintainability)

Rule 2: Architecture Documentation

IF (modifying component structure OR data models OR system design)
THEN (update relevant C4 architecture documents: ARCHITECTURE.md, DATA_MODEL.md, etc.)
ELSE (documentation drift - refer to c4-architecture-documentation skill)

Rule 3: Bilingual Documentation

IF (user-facing text OR Korean martial arts terminology)
THEN (provide both Korean and English with romanization where applicable)
ELSE (incomplete documentation for international audience)

Rule 4: Security Documentation

IF (security-related change OR authentication/authorization)
THEN (update SECURITY_ARCHITECTURE.md AND add ISMS policy references)
ELSE (security documentation gap - refer to security-architecture-validation skill)

Core Patterns

JSDoc Format

/**
 * Calculates damage multiplier based on trigram stance alignment.
 *
 * Uses the Eight Trigram (팔괘) opposition system to determine
 * effectiveness of attacks between different stances.
 *
 * @param attackerStance - The attacker's current trigram stance
 * @param defenderStance - The defender's current trigram stance
 * @returns Damage multiplier between 0.5 (disadvantage) and 2.0 (advantage)
 *
 * @example
 * ```typescript
 * const multiplier = calculateStanceMultiplier('geon', 'gon');
 * // Returns: 1.5 (Heaven vs Earth advantage)
 * ```
 *
 * @see {@link TrigramStance} for valid stance values
 */
export function calculateStanceMultiplier(
  attackerStance: TrigramStance,
  defenderStance: TrigramStance,
): number { /* ... */ }

Interface Documentation

/**
 * Represents a vital point (급소) target in the combat system.
 *
 * @property names - Bilingual names (Korean, English, romanized)
 * @property position - 2D coordinates on the character model
 * @property category - Anatomical category (neurological, cardiovascular, etc.)
 * @property severity - Impact severity level
 */
export interface VitalPoint {
  readonly id: string;
  readonly names: BilingualText;
  readonly position: Position;
  readonly category: VitalPointCategory;
  readonly severity: VitalPointSeverity;
}

Component Documentation

/**
 * CombatHUD displays the heads-up display during combat.
 *
 * Renders player health, ki energy, stance indicator, and
 * combat log using Html overlays over the Three.js scene.
 *
 * @remarks
 * Uses KOREAN_COLORS for consistent cyberpunk Korean aesthetic.
 * All text is bilingual (Korean | English).
 *
 * @example
 * ```tsx
 * <CombatHUD
 *   player={playerState}
 *   width={1200}
 *   height={800}
 *   isMobile={false}
 * />
 * ```
 */

Required Architecture Documents

Testing Requirements

• ✅ TypeDoc generates without errors (npm run docs)
• ✅ All public APIs have JSDoc comments
• ✅ Architecture documents are consistent with code
• ✅ Korean terminology includes romanization
• ✅ README.md is current and accurate

Compliance

• ISO 27001:2022: A.5.37 (Documented operating procedures)
• NIST CSF 2.0: GV.PO (Policy), ID.AM (Asset Management)
• Hack23 ISMS: Information Security Policy, Secure Development Policy

흑괘의 문서화 - Documentation of the Black Trigram

Source: Hack23/blacktrigram — distributed by TomeVault.