Back to all reviewers

Define technical terms clearly

jj-vcs/jj
Based on 10 comments
Markdown

Always define technical terms and concepts explicitly in documentation rather than assuming reader knowledge. Avoid ambiguous phrasing that could be interpreted multiple ways.

Documentation Markdown

Reviewer Prompt

Always define technical terms and concepts explicitly in documentation rather than assuming reader knowledge. Avoid ambiguous phrasing that could be interpreted multiple ways.

When introducing technical terms:

  • Provide clear, concise definitions inline rather than relying solely on external links
  • Use precise language that eliminates ambiguity
  • Be explicit about technical concepts even if they seem obvious

Examples of good practice:

# Good: Clear definition
* `.trailers() -> List<Trailer>`: The trailers at the end of the commit 
  description that are formatted as `<key>: <value>`.

# Bad: Ambiguous phrasing  
* `.trailers() -> List<Trailer>`: The trailers at the end of the commit
  description, formatted as `<key>: <value>`.
# Good: Precise terminology
* `.synced() -> Boolean`: For a local bookmark, true if synced with all tracked remotes.

# Bad: Imprecise terminology
* `.synced() -> Boolean`: For a local bookmark, true if synced with all remotes.

This prevents confusion, reduces the need for readers to maintain external references, and ensures documentation is self-sufficient. Pay special attention to terms that may have different meanings in different contexts or tools.

10
Comments Analyzed
Markdown
Primary Language
Documentation
Category

Source Discussions