# Improve Developer Documentation Quality

Weak documentation slows onboarding and makes code harder to maintain. This skill guides README, JSDoc, and inline comment reviews with practical standards.

## Install

```bash
npx skillstore add danielpodolsky/documentation-fundamentals
```

## Metadata

- Status: approved
- Slug: danielpodolsky-documentation-fundamentals
- Skillstore revision: r1
- Version status: missing
- Tree hash: 673d8c3a6131e25bdcc8d6229fe2f41424c7303623ec58a937199cd29313e312
- Author: DanielPodolsky
- GitHub username: DanielPodolsky
- License: MIT
- Repository: https://github.com/DanielPodolsky/mentor-spec/tree/main/.claude/skills/fundamentals/documentation
- Ref: 34f316ba14ef36c7a620fc09f2676d2429997a77
- Supported tools: Claude, Codex, Claude Code
- Audit status: complete
- Agent install advisory: allowed
- Manual install advisory: allowed
- Artifact signature: available
- Audit attestation: unavailable
- Human verification: not\_verified
- Risk factors: external\_commands
- Quality score: 78
- Quality tier: bronze
- Public page: https://skillstore.pages.dev/skills/danielpodolsky-documentation-fundamentals
- Manifest: https://skillstore.pages.dev/api/skills/danielpodolsky-documentation-fundamentals/manifest

## Capabilities

- Reviews comments for the WHY not WHAT principle.
- Checks README files for purpose, problem, installation, usage, and contribution guidance.
- Provides JSDoc guidance for parameters, returns, errors, examples, related APIs, and deprecation notes.
- Identifies obvious comments, stale comments, magic numbers, commented-out code, and scaffold README text.
- Supplies focused review questions for documentation feedback.

## Use Cases

- Review README readiness: Check that a README explains purpose, installation, quick start, and contribution flow before release.
- Improve API comments: Revise JSDoc so exported functions explain parameters, returns, errors, examples, and intent.
- Coach code reviews: Use focused questions to teach when comments add context and when code should stand alone.

## Prompt Templates

### Basic README Review

```
Review this README against the five essentials: purpose, problem, installation, quick start, and contribution guidance. List missing sections and concrete fixes.
```

### Inline Comment Cleanup

```
Review these inline comments. Flag comments that only repeat the code. Keep comments that explain intent, constraints, or business context.
```

### JSDoc Completeness Check

```
Evaluate this API documentation for JSDoc completeness. Check parameters, returns, errors, examples, related APIs, and deprecation notes.
```

### Repository Documentation Plan

```
Create a documentation review plan for this repository. Prioritize README gaps, exported API docs, inline comments, and stale documentation risks.
```

## Limitations

- Does not generate project-specific facts without source material.
- Does not validate whether README commands actually run.
- Does not replace security, legal, or API correctness review.
- Does not include automation scripts or parsers.

## Best Practices

- Document why decisions exist when code already shows behavior.
- Keep README steps copy-paste ready and tested by a new developer.
- Update comments when behavior changes, or remove comments that no longer add context.

## Anti Patterns

- Adding comments that restate variable names, loops, or assignments.
- Leaving commented-out code instead of relying on version history.
- Publishing scaffold README text that does not explain real purpose or setup.

## Security Audit

- Audited at: 2026-07-06T10:42:26.764\+00:00
- Summary: All static findings are false positives caused by Markdown fences, inline code formatting, or prose examples in SKILL.md. I found no executable scripts, prompt injection, data exfiltration intent, or system reconnaissance behavior in the reviewed skill.

## Stats

- Views: 220
- Downloads: 9
- Favorites: 0
- Popularity score: 0