Back to all reviewers

avoid subjective language

prometheus/prometheus
Based on 6 comments
Markdown

Avoid subjective terms, unexplained jargon, and assumptions about user knowledge in documentation. Replace subjective language like "obvious" with descriptive explanations, define technical terms that may not be familiar to all readers, and break down compact technical descriptions into more accessible language.

Documentation Markdown

Reviewer Prompt

Avoid subjective terms, unexplained jargon, and assumptions about user knowledge in documentation. Replace subjective language like “obvious” with descriptive explanations, define technical terms that may not be familiar to all readers, and break down compact technical descriptions into more accessible language.

Examples of improvements:

  • Instead of “the behavior is obvious” → “the result sample value is generated by applying the binary operator to the two input values in a straightforward way”
  • Instead of “qualifying I/O operations” → explain what specific operations are affected
  • Instead of “keyword” → use more descriptive terms like “function” or “expression”
  • Break down compact descriptions: “returns the estimated standard deviation… based on the geometric mean” → “returns the estimated standard deviation… For this estimation, all observations in a bucket are assumed to have the value of the mean of the bucket boundaries”

This approach makes documentation more inclusive and accessible to users who may be learning or feeling overwhelmed, rather than assuming expert-level familiarity with concepts.

6
Comments Analyzed
Markdown
Primary Language
Documentation
Category

Source Discussions