Considering using one line per sentence

[LinusSch]

Well, I had a thought.

Markdown is designed for maximally human-readable source files, hence it makes sense to wrap lines and the linter suggests the same. However, git is of course line-oriented. If we stick to using one line per sentence, git becomes as powerful as it is meant to be for version control and collaboration.

Documentation should rarely have long sentences anyway. It makes sense to have a few pages with more long-form reading content, when the user needs to learn a complete concept rather than look up a specific detail. One example is the excellent Introduction to clusters page from the Slurm course which would not be out of place in our documentation. But in general, documentation is best treated as a reference where the user considers almost everything to be a detail, something to be looked up as quickly as possible.

The drawback to this approach is that (at least for me) some clever setup of the text editors we use to write the documentation is needed to keep the authoring experience reasonable. The benefit is that when several people work on the same text, this makes git handle that gracefully.

[JerkerNvB]

I am pretty neutral, do what you find is the best!

[paran1]

It is quite rare that several people edit the same docs page at the same time, so I dont see how this is a problem here.

I am reading the documentation as I write it, so readability matters in the markdown files. Adding extra line-breaks will make it harder to read and get an overview. The suggested layout also have a high risk of affecting the language, as we would start to look at each sentence by it self.

I realize you suggest editor configs to work-around this. But we don't have a default editor, people use everything from emacs, vim, to VS code and even the github online editor.

Git internally is not line-oriented at all, it stores the file content as blobs. The default diff tools used to show changes are line oriented, but there are alternatives to those you can investigate that might show changes within text paragraphs more clearely. (I have head good things about difftastic, but never tried it.)

[richelbilderbeek]

I enjoy the suggestion and I enjoy your general writing ideas. I encourage you to apply your ideas to content you care about. The more complex text originates from well-willing colleagues that had no time to simplify it at that moment, so they will understand and thank you too.

In the end, I most prefer following the linter's style (i.e. max 80 characters per line), as making one exception opens up the floodgates for more exceptions. Also, it avoids work that has no visible impact to the user.