Sentence Length Rule

This rule checks for sentences that exceed 30 words in length. It's designed to promote clearer, more digestible writing by encouraging authors to break down long, complex sentences into shorter ones.

The motivation behind this rule is important: shorter sentences are generally easier to read and understand. Long sentences can become convoluted, making it harder for readers to follow the main point or maintain their attention. This is especially crucial in technical documentation where clarity is paramount.

Examples

✅ Good (under 30 words):

  • "The application server processes incoming requests and returns responses to clients."
  • "To configure the database, open the settings panel and enter your credentials."

❌ Flagged (over 30 words):

  • "The application server processes incoming requests from multiple client endpoints simultaneously while maintaining session state and ensuring proper load distribution across all available resources in the cluster for optimal performance."
  • "When implementing the authentication system, developers need to consider various security protocols, encryption methods, and user validation techniques while also ensuring the system remains compatible with existing infrastructure and maintains acceptable performance levels."

The rule will flag any sentence exceeding 30 words with the message "Try to keep sentences short (< 30 words)."

Rule Source

This rule comes from: https://github.com/jonathanalgar/smarteditor

Rule Definition

description: Try to keep sentences short (< 30 words). Split up sentence if possible
link: https://github.com/OutSystems/docs-validation/blob/master/style-guide/content.adoc#use-the-active-voice
extends: occurrence
message: "Try to keep sentences short (< 30 words)."
scope: sentence
level: suggestion
max: 30
token: \b(\w+)\b