Define formatting/writing style points?
Opened this issue · 5 comments
While getting down to the the small details, there's been plenty of fixes and sometimes overriding of previous changes in regards to things like table layouts. What about collecting some points of what we try to adhere to?
Some points to consider:
- Use
_for italics and**for bold in markdown - How do we format tables? For example, do we use a prefix
|? - Spelling issues, for example, do we want to consistently write
e.g.andi.e.asfor exampleandthat is? - ....
While getting down to the the small details, there's been plenty of fixes and sometimes overriding of previous changes in regards to things like table layouts. What about collecting some points of what we try to adhere to?
Yes, we should agree on style. 👍
Should we even add this to some readme somewhere? Maybe the one in the root?
Some points to consider:
* Use `_` for italics and `**` for bold in markdown
Sounds good to me. I've been trying to consistently change into exactly this.
* How do we format tables? For example, do we use a prefix `|`?
I have been changing into the following:
- No prefix
|. - No postfix
| - Exactly one space between
---s and|s in the header divider row on each side - Match width of columns for all rows (i.e. all are as wide as the largest), except when that becomes unreasonable.
- Match width of columns between format versions, when tables exists in both, to allow useful diffs.
- Last header divider matches the length of the header, not the contents
Some of these might be a bit controversial, so feel free to disagree and discuss.
My reasons for these particular choices is to keep line lengths as short as possible (since you can't line break tables), and keep diffs as useful as possible.
* Spelling issues, for example, do we want to consistently write `e.g.` and `i.e.` as `for example` and `that is`?
I prefer e.g. and i.e. when that is what you mean.
* ....
- Add newlines to make diffs maximally useful. I.e. newline after ever sentence, and newline at subclauses (i.e. after
,) when the sentence becomes too long and it makes semantic sense.
Should we even add this to some readme somewhere? Maybe the one in the root?
Yes, but not sure it should be directly user facing. Maybe a style-guide.md in the root or something like this.
Some points to consider:
* Use `_` for italics and `**` for bold in markdownSounds good to me. I've been trying to consistently change into exactly this.
Indeed, and I'm fine with this.
* How do we format tables? For example, do we use a prefix `|`?I have been changing into the following:
* No prefix `|`. * No postfix `|` * Exactly one space between `---`s and `|`s in the header divider row on each side * Match width of columns for all rows (i.e. all are as wide as the largest), except when that becomes unreasonable. * Match width of columns between format versions, when tables exists in both, to allow useful diffs. * Last header divider matches the length of the header, not the contentsSome of these might be a bit controversial, so feel free to disagree and discuss.
My reasons for these particular choices is to keep line lengths as short as possible (since you can't line break tables), and keep diffs as useful as possible.
Sounds fine to me.
* Spelling issues, for example, do we want to consistently write `e.g.` and `i.e.` as `for example` and `that is`?I prefer
e.g.andi.e.when that is what you mean.
I'd prefer the full written out for example and that is. It is a bit longer, but it is clearer, especially to people who are not (near) native english speakers and/or have Latin knowledge. I think it also leads to fewer small issues like those fixed in #325.
* ....* Add newlines to make diffs maximally useful. I.e. newline after ever sentence, and newline at subclauses (i.e. after `,`) when the sentence becomes too long _and_ it makes semantic sense.
Sounds fine to me, although I think we also shouldn't reformat text too much to put it in exactly this format, as that also decreases diff clarity.