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

Indicate intended move to 'Semantic Linefeeds' #506

Open
phillxnet opened this issue Oct 25, 2024 · 1 comment
Open

Indicate intended move to 'Semantic Linefeeds' #506

phillxnet opened this issue Oct 25, 2024 · 1 comment

Comments

@phillxnet
Copy link
Member

As per our https://github.com/rockstor/rockstor-website repo, where we have already accomplished this move, it is proposed that we indicate our intention in this repo.

I.e. our README.md and contributor doc guidelines should contain for example:

For contribution guidelines, see: Contributing to Rockstor documentation. For content additions/changes please stick to one sentence per line as this helps with translations and reviews of changes. Really long sentences may be broken at punctuation points. See Semantic Linefeeds which sites Brian W. Kernighan (1974).

Link otherwise lost in above comment: https://rhodesmill.org/brandon/2012/one-sentence-per-line/

As this makes PR review far easier and is a well established aid in doc maintenance. Especially given we already use the likes of Spnix to sort all our line-feeds etc out re presentation. The raw docs can then be in a form more amenable to maintenance.

It is not however proposed that we do this all in one go. That would be a massive change. But piecemeal. We then gain the maintenance advantages as our docs develop. And we need this doc/READMD.md notice entry to inform folks of our aims to move in this direction.

@Hooverdan96
Copy link
Member

I'll keep that in mind for future documentation PRs. Indeed, I probably ignored that for the most part.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants