One sentence per line?

[RalfJung]

The docs currently use a fixed-width style for formatting the source, so even small changes (adding a single word somewhere) can lead to large diffs. This also amplifies conflicts.

It might be worth to consider using one-sentence-per-line or one-logical-unit-per-line (allowing line-breaks at reasonable places even inside sentences). I have made good experience with that formatting. The change doesn't have to happen all at once; when existing text is changed one could encourage also changing it to the new format.

Cc @jyn514

[rylev]

I'd personally prefer to each paragraph on its own line. Most editors can visually line break (making reading the raw markdown easy).

[RalfJung]

That makes diffs quite bad though -- diff is line-based, which aligns well with one-sentence-per-line IMO.

[rylev]

That's true though I think GitHub's diff can handle intra-line diffs a bit better than plain diff, but this doesn't make local diffing nicer. I'm fine with moving to a per line scheme, but is their tooling that will do this automatically. It would be a huge when to not have to think about this at all when writing (similar to how rustfmt can be run on save in many editors).

[RalfJung]

Yeah tooling would be nice, but I'm not aware of any.

[pierwill]

I posted a (duplicate) issue in which I further discuss (rehash?) the benefits of this approach. I think it even tends to improve writing quality.

[tshepang]

@RalfJung this looks like can be closed, given #1241

[RalfJung]

#1241 was closed as a duplicate of this one. If we also close this one there's none left to track this. ;)

[jyn514]

I'm fine with moving to a per line scheme, but is their tooling that will do this automatically. It would be a huge when to not have to think about this at all when writing (similar to how rustfmt can be run on save in many editors).

this is my opinion as well - unless we have some way to enforce it, we'll use an enormous amount of energy to switch over the existing docs only to have new PRs not follow the format (and either have another round of back and forth to fix it, or it just won't get fixed because the reviewer won't think about it). Tooling would greatly reduce the effort for both the initial switch and continued maintenance.

FWIW I would expect this to be fairly simple to write ourselves - the hard part is distinguishing line endings from abbreviations (e.g.), but maybe there's some existing dictionary we can use?

[tshepang]

am working on the tool... it is so far not so clever, but I could already start using to migrate things gradually

[Noratrieb]

In the meantime, can we just disable the current checks? Reviewers can complain if a line gets too unwieldy. The current checks make it really annoying to write the documentation, which I consider to be really bad. Having a tool to enforce semantic line breaks sounds ok, but I think having no tool is way better than the current bad tool.

[saethlin]

We've been waiting over a year for the tool to arrive. It seems foolish to wait indefinitely. @tshepang are you still working on that tool? If not, we should invite others to finish it up.

[Noratrieb]

I have deleted the checks in #1952, btw.

[tshepang]

@saethlin I have intention to finish the tool, but I hope that does not discourage anyone to build something finished... my approach is bad anyways, and am very slow.

[jieyouxu]

Triage: unpinning this because while it's very nice to have, it's also not very urgent.