search

rockstor / rockstor-doc

Rockstor documentation
http://rockstor.com/docs
Other
25 stars 30 forks source link

Indicate intended move to 'Semantic Linefeeds' #506

Open phillxnet opened 6 days ago

phillxnet commented 6 days ago

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 commented 6 days ago

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