[Feature] Switch line formatting of README/Md files from fixed breaks to 1-sentence style

[briandominick]

Problem

The current Markdown files in this repo (at least those I've reviewed) use hard breaks inside sentences (probably at about column 80?).

This style is considered archaic and creates (at least) the following problems:

• Harder and more frustrating to maintain while authoring
• Introduces erroneous spaces at the ends of lines unless maintained meticulously
• Creates unnecessary diffs for line breaks

I believe all of this discourages at least some people from wanting to contribute to the docs.

Description

The optimal authoring style for lightweight markup formats like Markdown is the 1-sentence-per-line or "ventilated prose" method, where hard breaks are only used to create the spaces between sentences, so they're used after sentence-ending punctuation.

This imrproves diffs and provides clarity on the length of sentences at a glance. Most people report it is a nicer way to write compared to fixed hard breaks or contiguous paragraph wrapping.

Also this policy would be added to the creativecommons.github.io-source issue 792 for adding a Docs Guiidance page and maybe over time spread to other repos.

Alternatives

Other options are just letting lines wrap without breaks until paragraph breaks or else using Semantic linebreaks/linefeeds, which I think is too arbitrary and subjective for this multi-author environment.

Additional context

We should make this change on its own either before or after #467 as it will create one very busy diff.

Implementation

• [ ] I would be interested in implementing this feature.

[TimidRobot]

🎶 It's me, hi, I'm the archaic one

I strongly prefer hard wrapped code and documentation. However, I'll revisit that preference and the links provided.

[briandominick]

Heh, yeah you know I'm already developing a profile of you from being so close to your writing and code ;-) Just haven't determined whether you use Emacs or Vim yet. I'm willing to put in the effort on this, but you're most affected so there's really no point if it's mainly going to be you and the occasional me hacking away at these docs. Totally up to you. I'll happily follow through on the rest of my proposed changes even if you prefer we stick to the hard breaks.

[TimidRobot]

@briandominick please maintain the hard breaks, for now. With my currently scheduled deadlines and travel, I expect this issue might languish for a few weeks.

My background is in systems administration, so an on-server editor was necessary. By chance/circumstance I ended up with... https://github.com/creativecommons/cc-legal-tools-app/blob/9c219212ae837873dcdcc91da828eeb89337cc12/templates/base.html#L72

[briandominick]

Aha! I should have just guessed the default!

Will do re hard breaks. I'm old if not old school, so I can do archaic ;-). Happy travels and expect some more PRs from me this weekend or so, but I'm never in a rush to move things along, so happy to work at our mutual pace, whatever that ends up being.

[TimidRobot]

I think this article does a decent job of outlining the strengths of both soft wrapping and hard wrapping files: Coding Controversies: Hard Wrap vs Soft Wrap – Pursuit Of Laziness – A blog by Jesse Duffield

For me, subjectively, the benefits of hard wrapping are worth the cost. However, I do think we could better support the preference (ex. editor plugin recommendations).

[TimidRobot]

I updated the Foundational Tech PR with a Code Editor section to improve support for hard wrapping in VS Code:

• creativecommons/creativecommons.github.io-source/pull/808

[TimidRobot]

(also thanks again for 1-sentence-per-line or "ventilated prose" info. i'd like to explore that further)