Refactor the documentation to use one line per sentence

[HonkingGoose]

What would you like Renovate to be able to do?

Contributing to the documentation is not very pleasant for me, due to the way the Markdown files are formatted.

Current style:

Beginning of paragraph sentence. This sentence really should be on its own line, but I'm making it extra long for extra effect, look at me I can type a long sentence. Now here is another sentence to make the line extra extra long.

Beginning of paragraph sentence. Let's make another long line for dramatic reasons. Now where was I on this line, the softwrap is making this hard to see. If only there was a better way to format this text...

Proposed style:

Here is the starting sentence for this paragraph.
This sentence also belongs to the paragraph.
Here's another sentence that belongs to the paragraph.
Notice how lines are separated visually.
This also helps when dealing with line based changes in Git.

Let's start a new paragraph, notice how it is separated by a newline?
Here is another sentence that belongs to the new paragraph.
As an added bonus, it also nudges writers to write shorter and simpler sentences, if I keep on going with my sentence, it starts to look very odd, maybe I should shorten or simplify this sentence, this sentence is getting ridiculous now, but let's write some more, what harm could it do? What's that noise?! Is that a møøse I hear out thër?

The writers guild regrets that you had to read that abomination of a sentence.
We have taken cørrective mësures to ensure this wøn't happen again.
We've dispatched our team of grammar møøses to remedy this issue.

Here's a sentence that starts a new paragraph.
This line belongs to this paragraph also.
I really like this style of formatting text, it looks really clean!

Did you already have any implementation ideas?

Go through the documentation and change the files so that they all conform to the proposed style. There are no user facing changes, the docs will look the same on their end.

Are there any workarounds or alternative ideas you've tried to avoid needing this feature?

Turn on soft-wrap in the editor when working on the documentation. This still makes it hard to see where sentences begin and end, so it's not really a good solution for me. I also noticed that searching for a specific string becomes very confusing when lines are overly long.

Is this a feature you'd be interested in implementing yourself?

Yes, you don't have to do anything but review the final result. I will do the manual labor for you. :smile: :wink:

[rarkins]

Is there any references for this which would make the decision easier, including:

• any thought leadership articles?
• any large projects debated this before and/or adopted it?

[rarkins]

Rejected as a rule for prettier, which we use: https://github.com/prettier/prettier/issues/3302

I definitely don't see any consensus on this. We don't suffer a reflow problem because we don't hard wrap. And GitHub is good at showing which words changed in a line these days so that reduces the benefit.

Maybe demo one file changing so we get a feel for it?

[HonkingGoose]

Any large projects debated this before and/or adopted it?

The ProGit 2 book project adopted this standard. I know this, because I contribute to it on a regular basis. They have a entire book to maintain, I think that qualifies as a large project.

Take a look at the .asc files in the chapter directories: they all conform to the standard that I'm proposing: https://github.com/progit/progit2/tree/master/book.

Any thought leadership articles?

It's an official recommended practice of the Asciidoctor project (you can use Asciidoctor to write books): https://asciidoctor.org/docs/asciidoc-recommended-practices/#one-sentence-per-line

They make a better case for my proposal than I could myself, quote from the link above:

Here are some of the advantages of using the sentence per line style:

• It prevents reflows (meaning a change early in the paragraph won’t cause the remaining lines in the paragraph to reposition).
• You can easily swap sentences.
• You can easily separate or join paragraphs.
• You can comment out sentences or add commentary to them.
• You can spot sentences which are too long or sentences that vary widely in length.
• You can spot redundant (and thus mundane) patterns in your writing.

Rejected as a rule for prettier, which we use: prettier/prettier#3302

Well Prettier call themselves "An opinionated code formatter" on their website for a reason... I like and use Prettier for most of my projects, as it prevents a lot of discussion over code style. I don't think you'll be surprised when I say that I don't agree with this particular decision. :smile:

Maybe demo one file changing so we get a feel for it.

I will go make a pull request which changes one file, so that you can take a look at the style on a real file. :smile: EDIT: I made the pull request, take a look: #7546.

[JamieMagee]

I don't have a strong opinion on this style one way, or the other, but I do think the lack of automation around this practice is a negative. Right now, all our style rules are automatically enforced. Making this change would mean that there's a manual step involved as well.

[rarkins]

When Googling earlier it looked like someone had added a markdown-lint plugin for it. I would also prefer we could automate it

[HonkingGoose]

The markdown-lint main package is on a 0.x version range. The API for markdown-lint is not yet stable, so any plugin that uses the API can break at any time.

I think I found the markdown-lint plugin that @rarkins is talking about: https://github.com/JoshuaKGoldberg/sentences-per-line. The sentences-per-line plugin looks promising, but it needs work:

• It's missing tests to prove the plugin works as it should.
• It's not seen dependency updates since 2018.
• It's not maintained by the plugin developer anymore.
• The plugin is using the internal API of markdown-lint which is not stable to program against.

Based on the instability of the markdown-lint package and it's surrounding ecosystem, I do not recommend that the Renovate team take those packages as dev-dependencies to automate this problem.

If fixing this with automation means taking on badly maintained and unstable packages, I'd rather leave things as they are.

[HonkingGoose]

I've closed the example pull request #7546, because the Renovate project is in the middle of migrating to Docusaurus v2. It makes no sense to open PR targeting the docs that are going to be migrated anyways.

I'd rather wait until the Docusaurus v2 docs are ready for pull requests, that way I'm not bothering @viceice with small stuff while he's working on the docusaurus branch.

@rarkins If you want me to improve the docs by implementing my proposal, let me know when the Docusaurus based docs are ready for pull requests. I'm not really sure if you wanted this change or not?

[HonkingGoose]

@rarkins Do you want me to change all the docs to follow the proposed style?

[rarkins]

Would it be a manual job or have you found a way to automate it? Ideally we'd have a way of keeping it correct using linting too

[HonkingGoose]

I would be a manual job.

See https://github.com/renovatebot/renovate/issues/7545#issuecomment-716207546 for reasons why I don't think we can automate this in a safe manner.

[rarkins]

How about this one? https://github.com/IQTLabs/textlint-rule-one-sentence-per-line

It has tests, and seems that it can "fix". So at least it could save plenty of manual work.

[HonkingGoose]

That would be loads better, the base textlint package sees regular releases and uses a proper dependency management bot.

The plugin textlint-rule-one-sentence-per-line has tests, and a "fix" mode, though that plugin needs to upgrade to a newer version of the base package textlint. Also note that this plugin has nobody working on it actively, and has no outside contributors, so the bus-factor is one.

[rarkins]

The impact of it stopping working is fairly low though

[JamieMagee]

Could we write our own custom prettier plugin for this?

[HonkingGoose]

Could we write our own custom prettier plugin for this?

I think that would be possible. There are some edge cases to consider though. I will be glad to help you figure out the testcases. :wink:

[viceice]

I think it should be easy doable to write a prettier plugin based on the textlint rule

[rarkins]

I'm ok with that as long as we don't end up needing too many ignore statements throughout our markdown.

Also ok to merge the manual migration now prior to any automation.

[renovate-release]

:tada: This issue has been resolved in version 23.67.1 :tada:

The release is available on:

• GitHub release
• 23.67.1

Your semantic-release bot :package::rocket: