Add basic style guide #53
Conversation
|
preview available: https://docs.tds.cscs.ch/53 |
STYLE.md
Outdated
| - Format paragraphs with one sentence per line for easier diffs. | ||
| - Leave a space before and after headings. | ||
|
|
||
| ## Headings are Written in Title Case |
There was a problem hiding this comment.
This seems to be the case for most headings, but is not completely consistent. My purely subjective opinion is sentence case for headings as well, but don't care too much as long as we stick to one style.
There was a problem hiding this comment.
I've been doing and suggesting the opposite... But I also do not care as long as we are consistent.
There was a problem hiding this comment.
Personally I am more comfortable with lower case if I had to choose (except for the first word in the heading).
Of course, I am almost certainly wildly inconsistent in practice.
There was a problem hiding this comment.
Since we all seem to actually agree that sentence case is nicer, let's make it that in the style guide and gradually try to stick to it/update titles as we bump into title case.
STYLE.md
Outdated
| Aim to include examples, notes, warnings using [admonitions](https://squidfunk.github.io/mkdocs-material/reference/admonitions/) whenever appropriate. | ||
| They stand out better from the main text, and can be collapsed by default if needed. | ||
|
|
||
| !!! example "Example one" |
There was a problem hiding this comment.
Some admonition titles use all lower case, some sentence case. Preference?
There was a problem hiding this comment.
Honestly, I don't really care too much.
If the admonitions inside a page are are consistent, it probably isn't a big deal?
There was a problem hiding this comment.
Of course not a big deal. This is just aiming to bring a bit of consistency, but we'll break the rules anyway, intentionally or unintentionally.
I'll review later, but we already have a "Contributing" section, therefore it could go there, or as a subsection of that? |
I'm not sure how I missed that, thanks for pointing it out! Seems like a great place to put it. |
|
preview available: https://docs.tds.cscs.ch/53 |
|
I moved the style guide to a subsection in |
|
This overlaps with another PR made at about the same time, that discusses "how to link" and provides justification for why we don't break sentences. |
docs/contributing/index.md
Outdated
|
|
||
| 1. The first item can look like this, | ||
| 2. The second like this, and | ||
| 3. The third item like this. |
There was a problem hiding this comment.
I would put the and at the start of the third line, and star each line with a lower case letter (the whole list is a sentence, no?)
I agree that care should be taken with formating lists, but it is tricky to canonicalize without being too strict. For example, I would format your list as follows:
contain multiple sentences:
- the first item can look like this;
- the second like this;
- and the third like this.
There was a problem hiding this comment.
but it is tricky to canonicalize without being too strict
This is probably key, so in the end these are just guidelines.
Agree on capitalization (see #53 (comment)). I feel like it's more common to have the "and" or "or" trailing on the second-to-last item though?
There was a problem hiding this comment.
Honestly, I don't know.
It feels wrong to me, because if we use the oxford comma (as we should), the and comes after the comma.
I think if people go to enough effort to punctuate their lists with care, that's enough?
There was a problem hiding this comment.
If it's all the same to you, I'd leave it with the trailing and/or on the second-to-last item, but indeed, let's not actually bikeshed this too much.
I think if people go to enough effort to punctuate their lists with care, that's enough?
Yes, of course.
Replaced by more detailed formatting section
|
preview available: https://docs.tds.cscs.ch/53 |
Co-authored-by: Rocco Meli <r.meli@bluemail.ch>
|
preview available: https://docs.tds.cscs.ch/53 |
|
preview available: https://docs.tds.cscs.ch/53 |
|
preview available: https://docs.tds.cscs.ch/53 |
This adds a basic
STYLE.mdin the root of the repo as a basic style guide (the filename and location is not a convention as far as I know, I just thought it fits). I've tried to capture most of the current style. That doesn't mean we have to keep it this way. Bikeshed away with review comments!It'd be nice to have this in the actual docs as well, but I wasn't sure where to put it yet so it's currently outside the main
docstree.