Opentelemetry-specification: Settle on linebreak style

[c24t]

Motivated by https://github.com/open-telemetry/opentelemetry-specification/pull/190#discussion_r306238811.

We don't have a consistent style for wrapping long lines of prose. It may not be worth the trouble to enforce a specific style, but we should either pick one now or agree not to enforce this going forward.

Of the files in the spec that have a mostly consistent style:

Hard breaks at 80 chars: 6 files, generally @SergeyKanzhelev and @bogdandrutu
Hard breaks at > 80 chars: 2 files, generally @songy23
Break at end of paragraph: 3 files, generally @tigrannajaryan, @mayurkale22, and @iredelmeier

This is almost entirely a matter of personal taste, so if anyone has an opinion I'd like to hear it. I'd prefer to put a single break at the end of each sentence and blank lines in between paragraphs because this tends to produce nice diffs.

[arminru]

+1 for your proposal
Nice diffs are nice and it makes the raw MD files easier
to read since the breaks are more natural rather than chopping
off sentences randomly with hard breaks.
In addition to that, hard breaks are annoying to obey when one is editing simple stuff using the web interface or applies review suggestions there.

[bogdandrutu]

I would personally vote to have a limit because otherwise some lines will have >300 chars (or even more).

[c24t]

Applying review suggestions is a good point: since github doesn't let you suggest multiline hunks this means the OP has to break out the editor for even simple changes.

I'm happy with 300+ char lines since I can soft wrap them in my own editor.

[c24t]

Using soft breaks also means that reviewers don't have to change the browser size to match the text width on the review page to see a nice diff.

Compare hard breaks in #163:

to soft breaks in #186:

[tigrannajaryan]

I suggest that we do one of these:

1. Hard breaks at 80 chars.
2. Break at end of paragraph.

Either works fine for diffing in Github. 1 is more manual work, 2 requires your editor to support soft wrapping. My vote goes to 2, but I am open to doing 1 if majority wants that.

I would refrain from hard breaking at large column numbers precisely because of what @c24t said above.

[carlosalberto]

I also vote for having a limit - either 80 or 100 should be fine (and friendlier).

[GreyCat]

If I can chime in, from my perspective, hard limit at 80 or 100 will be the best for reasons like:

• Embedding docs into code comments (as docstrings, etc) without major reformatting
• Compatibility with large set of tools (Azure DevOps code viewer, to some extent, GitHub)
• GitHub only allows line-level precision of comments, so having multiple hard lines makes it easier to pinpoint things to comment on in large paragraph.

[iredelmeier]

Strong support for soft breaks:

• Makes editing MUCH easier. (Copy editing, which we very much need to do, basically requires that we reformat with soft breaks as a first step. This is especially true if we get help from a technical writer who's less comfortable with tooling that has explicit support for hard breaks.)
• Better git history
• Allows for more personal customization in editors

[Oberon00]

I think that soft breaks would be best, as, contrary to source code files, soft-wrapping works very well for (plain english) text files. Regarding the pin-pointing things in lines issue: You could add a hard break after every sentence, or after every clause (wherever you think it makes sense semantically).

[c24t]

From the spec SIG call today: let's use soft breaks, revisit if we decide that this was a mistake.