SUSE / doc-styleguide

SUSE Documentation Style Guide
https://susedoc.github.io/doc-styleguide/main/html/style-guide/
Other
14 stars 4 forks source link

Increasing the Word Limit for Sentences #299

Closed alexvonme closed 1 month ago

alexvonme commented 2 months ago

This issue concerns the Sentence structure section.

May I ask if the word limit could be increased to 24 or 28 words? SUSE has one of the lowest word limits that I've come across, and I think this might be counterintuitive.

I'm the GSoC student for Kanidm where under my mentor @firstyear, I'm trying to improve the documentation. Kanidm is under the openSUSE project, and we are planning to standardize the documentation in line with the SUSE style guide. To do so, I hope to improve the vale style guide, which we were aiming to adopt. Just today, I submitted a pull request (openSUSE/suse-vale-styleguide#95) to check for sentence length.

However, the 20-word limit for each sentence simply doesn't work well with a network-related software like Kanidm.

To illustrate with an example, the RADIUS section of the documentation starts with the following sentence:

Remote Authentication Dial In User Service (RADIUS) is a network protocol that is commonly used to authenticate Wi-Fi devices or Virtual Private Networks (VPNs).

This sentence is "clear and direct", as suggested, but because it mentions networking tools, it is above 20 words. Apart from abbreviation explanations, there are also a lot of multi-word phrases such as "host name" and "end user". Furthermore, as an identity management server, Kanidm has to often explain its functions. At least, to a point that doesn't limit its user base to senior developers with extensive experience.

dariavladykina commented 1 month ago

I did a research on tech writing resources: Some of them confirm our stance be recommending up to 20 words: MDN or Proxmox Some agree on 25 words, like here. Some allow up to 30 words: MIT

alexvonme commented 1 month ago

Some additional examples are: GitLab - In internal Vale rule - 25 Datadog - In internal Vale rule - 25 Google - Style Guide - 26 Medusa - In internal Vale rule - 30 RedHat - Style Guide - 32 Meilisearch - In internal Vale rule - 40 Docker - In internal Vale rule - 40

An alternative that I mentioned was to introduce two goals. For example, to suggest keeping sentences to 20 words and making allowance for sentences with technical terms such as RADIUS to 28 words.

Either way, I would argue that 20 words is unenforceable for network related software.

Edit: Fixed link for GitLab

alexvonme commented 1 month ago

I did a research on tech writing resources: Some of them confirm our stance be recommending up to 20 words: MDN or Proxmox Some agree on 25 words, like here. Some allow up to 30 words: MIT

The MIT suggestion may be useful to craft an alternative here. Like them, SUSE could suggest aiming for 20 words while introducing a somewhat hard limit of 28. This could easily be applied through Vale with two separate rules. One that raises a light warning to keep the sentence below 20 words while a second higher suggestion (or even the highest, an error) rule that enforces the 28-word limit. Introducing a goal and a limit separately is relatively uncommon, but hardly unprecedented.

cwickert commented 1 month ago

To illustrate with an example, the RADIUS section of the documentation starts with the following sentence:

Remote Authentication Dial In User Service (RADIUS) is a network protocol that is commonly used to authenticate Wi-Fi devices or Virtual Private Networks (VPNs).

IHMO this a bad example as the written out acronyms already make 11/20 words. You don't have to write out VPN here, this is common knowledge.

But even then you could simplify to 20 words: Remote Authentication Dial In User Service (RADIUS) is a network protocol to authenticate Wi-Fi devices or Virtual Private Networks (VPNs).

Nevertheless I'm fine with 25 words.

dariavladykina commented 1 month ago

The Stylewich committee has decided to raise the word limit to 25 words. The style guide will be updated, too. @alexvonme please feel free to update it in the PR. Thank you!

alexvonme commented 1 month ago

Happy to be of service. Thanks for seriously engaging with my arguments. I'll update the Vale style guide shortly.