Remove parentheses for clarity (EK00004)
Folding parenthetical asides into the sentence keeps each line of your documentation a single, clear thought. Learn why, with examples.
Folding a parenthetical aside into the main sentence keeps a single, direct thought that readers follow in one pass. EkLine flags parentheses that interrupt a sentence rather than define an acronym (rule EK00004) and suggests rewriting the line without them.
Why remove parentheses in documentation?
Section titled “Why remove parentheses in documentation?”Parentheses split a reader’s attention between two thoughts at once, which slows comprehension and hides information that belongs in the main sentence. Screen readers and translation tools also handle a straight sentence more reliably than a nested aside. Removing the parentheses often reveals whether to keep the content or cut it.
What EkLine flags
Section titled “What EkLine flags”EK00004 flags a pair of parentheses that wraps an aside rather than defines an acronym.
- ❌ Incorrect: The CLI (which runs locally) checks your docs.
- ✅ Correct: The CLI runs locally and checks your docs.
- ❌ Incorrect: Set the timeout (in seconds).
- ✅ Correct: Set the timeout in seconds.
How to fix
Section titled “How to fix”Fold the parenthetical content into the main sentence, or move it to its own sentence. When the parentheses define an acronym on first use, keep them and ignore the rule for that line.
When are parentheses acceptable in documentation?
Section titled “When are parentheses acceptable in documentation?”Parentheses that define an acronym on first use, such as Cascading Style Sheets (CSS), are fine. The rule targets asides that interrupt a sentence rather than define a term.
How do you rewrite a sentence to remove a parenthetical aside?
Section titled “How do you rewrite a sentence to remove a parenthetical aside?”Fold the parenthetical content into the main sentence, or move it to its own sentence.
Rule details
Section titled “Rule details”| Property | Value |
|---|---|
| Rule ID | EK00004 |
| Category | Sentences and phrases |
| Default severity | Suggestion |
| Enabled by default | No |
Ignore this rule
Section titled “Ignore this rule”To keep a flagged aside on one line, add an inline comment with a reason:
<!-- ekline-ignore-next-line EK00004 -- aside kept for legal clarity -->The service (as defined in the agreement) runs locally.To disable the rule across your project, add it to the ignore list in your configuration file.