This rule checks for the presence of semicolons (;) in sentences and suggests simplifying sentences that contain them. The motivation behind this rule is that semicolons often indicate complex, lengthy sentences that could be broken down into simpler, more digestible parts. Microsoft's style guide, which this rule references, generally recommends using simpler sentence structures for clarity and readability.
Long, complex sentences with semicolons can be harder for readers to follow, especially in technical documentation. Breaking these sentences into shorter, distinct statements often improves comprehension and makes the content more accessible.
✗ Incorrect:
The function accepts three parameters; it returns a boolean value.
✓ Better:
The function accepts three parameters. It returns a boolean value.
✗ Incorrect:
The API requires authentication; users must provide valid credentials; rate limits apply.
✓ Better:
The API requires authentication. Users must provide valid credentials. Rate limits apply.
The rule will flag any sentence containing a semicolon and suggest reviewing it for potential simplification.
This rule comes from: https://github.com/mesosphere/dcos-docs-site
extends: existence
message: "Try to simplify this sentence."
link: https://docs.microsoft.com/en-us/style-guide/punctuation/semicolons
nonword: true
scope: sentence
level: suggestion
tokens:
- ';'