README: one sentence per line? #376

New Issue

2022-10-20T17:25:37Z

pat-s commented

2022-10-20 17:25:37 +00:00

(Migrated from gitea.com)

Partly discussed in #348 but not really addressed.

I am a fan of the "one sentence per line" practice in .md documents.
Simplifies reviews a lot as the context is always clear.
Also one does not need to search for the dot which terminates a sentence but can rest assured that each line = one sentence.

In the same way, I find "randomly" breaking sentences (i.e. on a fixed line length) quite hard to read.

@justusbunsi @luhahn Your opinion?

Partly discussed in #348 but not really addressed. I am a fan of the "one sentence per line" practice in .md documents. Simplifies reviews a lot as the context is always clear. Also one does not need to search for the dot which terminates a sentence but can rest assured that each line = one sentence. In the same way, I find "randomly" breaking sentences (i.e. on a fixed line length) quite hard to read. @justusbunsi @luhahn Your opinion?

justusbunsi commented

2022-10-20 17:40:59 +00:00

(Migrated from gitea.com)

There are two caveats when manually adding line breaks: different screen or IDE sizes, review using raw or rendered markdown.

I don't have a particular opinion on that. It's more important to me how the rendered Markdown file looks like when reading it as a user. While I prefer to review the raw version to spot rendering issues ?.

A different thing are PR descriptions, IMO. Most tools, Gitea as well, use the PR description as default (squash) merge commit body. So I like following the commit guidelines to make it easier reading the git log.

There are two caveats when manually adding line breaks: different screen or IDE sizes, review using raw or rendered markdown. I don't have a particular opinion on that. It's more important to me how the rendered Markdown file looks like when reading it as a user. While I prefer to review the raw version to spot rendering issues ?. --- A different thing are PR descriptions, IMO. Most tools, Gitea as well, use the PR description as default (squash) merge commit body. So I like following the [commit guidelines](https://www.git-scm.com/book/en/v2/Distributed-Git-Contributing-to-a-Project#_commit_guidelines) to make it easier reading the `git log`.

pat-s commented

2022-10-23 11:40:34 +00:00

(Migrated from gitea.com)

There are two caveats when manually adding line breaks: different screen or IDE sizes, review using raw or rendered markdown.

Aren't reviews always carried out on the source? When reviewing I want to add comments directly when I read the content - switching between the rendered version and the source is quite tedious, isn't it?

The issue with reviewing and sentences being broken across multiple lines is the context. Often in-line comments are made on a specific sentence and e.g. when using the "suggestion" feature in GH (Yes I know we are in Gitea), this becomes quite problematic. Whereas when following "one sentence per line", this feature is really nice to use.
Ofc the issue then applies in the same way on the paragraph level.

And for some reason I'd also prefer having the source being close to the rendered version ?

I don't have a particular opinion on that.

@luhahn What is your opinion?

> There are two caveats when manually adding line breaks: different screen or IDE sizes, review using raw or rendered markdown. Aren't reviews always carried out on the source? When reviewing I want to add comments directly when I read the content - switching between the rendered version and the source is quite tedious, isn't it? The issue with reviewing and sentences being broken across multiple lines is the context. Often in-line comments are made on a specific sentence and e.g. when using the "suggestion" feature in GH (Yes I know we are in Gitea), this becomes quite problematic. Whereas when following "one sentence per line", this feature is really nice to use. Ofc the issue then applies in the same way on the paragraph level. And for some reason I'd also prefer having the source being close to the rendered version ? > I don't have a particular opinion on that. @luhahn What is your opinion?

xeruf commented

2022-11-09 12:38:18 +00:00

(Migrated from gitea.com)

I recommend https://sembr.org :)

👀 1

pat-s commented

2022-12-27 09:19:45 +00:00

(Migrated from gitea.com)

@justusbunsi How do we want to proceed here? It seems nobody else wants to share their opinion right now. Maybe @techknowlogick?

I don't want to keep this issue open infinitely if we cannot find a conclusion here.

@justusbunsi How do we want to proceed here? It seems nobody else wants to share their opinion right now. Maybe @techknowlogick? I don't want to keep this issue open infinitely if we cannot find a conclusion here.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: lunny/helm-chart#376