Skip to content

Use paragraphs without hard breaks

William Chia requested to merge williamchia-master-patch-47958 into master

This MR reverts/updates !27858 (merged)

Whether the line break is at each sentence, or at a certain character limit (e.g. 80 characters), putting hard breaks in a paragraph makes copy very difficult to edit. Our official style guidelines for the blog and handbook should recommend against this practice.

Why soft wrapping is better

  • Easier editing When a paragraph is on a single line it is easier to edit. Complete thoughts are normally formated as paragraphs. Editing a thought usually requires editing multiple sentences, which is hard to do if they are broken up each on a line. This is even harder when lines are broken at a character limit because you need to reflow the hard breaks every time you change a word which is very tedious.
  • Easier reviewing Reading and scanning is easier if the text is formatted in paragraphs. If each sentence is on a line, or worse broken up at a certain character limit, it makes reading difficult.
  • Multi-line suggestions are hard Multi-line suggestions are very complicated to operate (you need to calculate offsets). Uninitiated users will not know that you can set offsets. For users that are not software developers, the concept of offsets is difficult to grasp and even if they know you can do multi-line comments it will be hard for them to understand how.
  • Better UX for the suggest feature If a paragraph is all on one line, then in most cases a multi-line edit is not needed. Clicking the comment button on the line brings up the full paragraph for you to edit. Even if you understand how to do multi-line edits it's just a much poorer UX since the product doesn't show you what you are editing until after you hit submit.

Soft breaks: Easy to start editing I get the whole paragraph when I click "suggest": image

Hard breaks: Can't select multiple lines/only get one line to edit:

image

Potentially our product should be updated to make this easier. Let's set a style guide that works with the functionality GitLab has now. We can always change and iterate in the future if GitLab changes.

  • Easier to get started Most people write in paragraphs in every other app they compose text in. Trying to enforce a rule like "break at every sentence" or "break at 80 characters" adds an unnecessary barrier to empowering everyone to contribute. Either it will slow down or dissuade folks from contributing or they simply won't do it because they didn't know. The natural way to write is one paragraph per line, we should use a boring solution here.

Why use hard breaks?

  • commenting/review Commenting on a change that is one word or one sentence within a large paragraph can be easier if the paragraph is broken into lines or a smaller length.
Edited by William Chia

Merge request reports