OpenParable
Skip to content
← Back to skills

Docs Guidelines

Development
docs-guidelines

Docs Guidelines is an Agent Skill for development published in the RediSearch/RediSearch repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

General documentation guidelines that apply across all languages. Use this when writing or reviewing comments, docstrings, or doc headers in any code.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/RediSearch/RediSearch/blob/HEAD/.skills/docs-guidelines/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/docs-guidelines, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

Documentation Guidelines

General guidelines for writing code documentation. Language-specific skills (e.g. rust-docs-guidelines) layer on top of these.

Guidelines

  • Document every added component (e.g., struct, function, enum). Make sure your code additions are well commented, with concise explanations for a new reader.
  • Prefer code-enforced invariants over prose. If an assertion, type, enum, or test can express the constraint, add it. Add a comment where a non-trivial statement that can help the reader is needed on top of the above. Comments can drift; code mostly doesn't.
  • State each fact in exactly one place. The owner is the definition, the interface, or the implementation — whichever is canonical. Other locations reference it by name, not by restating it.
  • Focus on why, not how. Don't restate what the code plainly does. Document non-obvious choices, invariants that are hard to infer, and constraints a maintainer would otherwise miss.
  • Do not document obvious behavior, callee implementation details, or duplicate the same detail across call sites.

Placement model

Each fact belongs to exactly one of these layers — pick the one that owns it and avoid restating it elsewhere:

  • Call sites — non-trivial local intent, assumptions, sequencing constraints, or edge cases specific to this usage.
  • Definitions and interfaces — the contract: inputs, outputs, errors, side effects, invariants.
  • Implementations — non-obvious internal choices, tradeoffs, workarounds.
  • READMEs — module-level context and architectural decisions.