Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

chore: following semantic line breaks in documentations #2123

Closed
staheri14 opened this issue Jul 18, 2023 · 10 comments
Closed

chore: following semantic line breaks in documentations #2123

staheri14 opened this issue Jul 18, 2023 · 10 comments
Labels
ice-box this label is automatically applied to all issues. it is removed after starting work needs:discussion item needs to be discussed as a group in the next sync. if marking an item, pls be prepped to talk proposal item is not yet actionable and is suggesting a change that must first be agreed upon

Comments

@staheri14
Copy link
Contributor

Problem

The following issue is more of a suggestion than a problem.
I'd like to recommend incorporating semantic line breaks into our documentation. The concept involves strategically placing line breaks at semantic boundaries. In markup languages like Markdown, single line breaks are typically invisible to readers, however, it offers several advantages to the authors and editors, as highlighted in the link provided:

Why Use Semantic Line Breaks?
For a writer, semantic line breaks allow the physical structure of text to reflect the logical structure of the thoughts that produce them.
For an editor, semantic line breaks make it easier to identify grammatical mistakes and find opportunities to simplify and clarify without altering original intent.
For a reader, semantic line breaks are entirely invisible — no changes to the source text appear in the final rendered output.

Proposal

Once/If the decision to implement semantic line breaks is finalized, we can update the relevant section to reflect this choice and effectively communicate it with the team.

@staheri14
Copy link
Contributor Author

@staheri14 staheri14 self-assigned this Jul 18, 2023
@rootulp
Copy link
Collaborator

rootulp commented Jul 18, 2023

I'm onboard with adopting semantic line breaks.

@MSevey
Copy link
Member

MSevey commented Jul 18, 2023

Seems good, would need to see an example in our case, I'm not quite sure what this looks like in practice.

@rootulp rootulp added proposal item is not yet actionable and is suggesting a change that must first be agreed upon and removed needs:triage labels Jul 18, 2023
@staheri14
Copy link
Contributor Author

Seems good, would need to see an example in our case, I'm not quite sure what this looks like in practice.

I have applied the semantic break-line rule in this PR for a sample.

@evan-forbes
Copy link
Member

evan-forbes commented Aug 24, 2023

I'm down SGTM

@mojtaba-esk
Copy link
Member

It seems easier to read, I am in

@rootulp
Copy link
Collaborator

rootulp commented Jan 21, 2024

How do we close this issue? It seems monumental to revisit every document in this repo and apply this rule. Should we only apply it for new docs?

@staheri14
Copy link
Contributor Author

staheri14 commented Feb 15, 2024

How do we close this issue? It seems monumental to revisit every document in this repo and apply this rule. Should we only apply it for new docs?

Initially, I think that would be sufficient to ensure that new documents adhere to semantic line breaks.
Also, the use of semantic line breaks can be added as a recommendation to the contribution section of the repo.

cc: @evan-forbes @rootulp please let me know what you think about this, then I'l proceed accordingly.

@staheri14
Copy link
Contributor Author

If anyone has different opinions about how to proceed with this issue, feel free to share.

@rootulp
Copy link
Collaborator

rootulp commented Feb 15, 2024

SGTM

@evan-forbes evan-forbes added needs:discussion item needs to be discussed as a group in the next sync. if marking an item, pls be prepped to talk ice-box this label is automatically applied to all issues. it is removed after starting work labels Feb 27, 2024
@evan-forbes evan-forbes added needs:discussion item needs to be discussed as a group in the next sync. if marking an item, pls be prepped to talk and removed needs:discussion item needs to be discussed as a group in the next sync. if marking an item, pls be prepped to talk labels Mar 11, 2024
@rootulp rootulp closed this as not planned Won't fix, can't repro, duplicate, stale Apr 1, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
ice-box this label is automatically applied to all issues. it is removed after starting work needs:discussion item needs to be discussed as a group in the next sync. if marking an item, pls be prepped to talk proposal item is not yet actionable and is suggesting a change that must first be agreed upon
Projects
None yet
Development

No branches or pull requests

5 participants