Add a small writing style guide#1448
Conversation
|
@wilzbach, thanks for your PR! By analyzing the annotation information on this pull request, we identified @quickfur and @zachthemystic to be potential reviewers. @quickfur: The PR was automatically assigned to you, please reassign it if you were identified mistakenly. |
| * Use a _neutral_ tone (No strong narrator = no first-person ("I", "we") nor second-person ("you")) | ||
| * Use a _formal_ style (No slang) | ||
| * Use the [American English spelling](https://en.wikipedia.org/wiki/American_and_British_English_spelling_differences) | ||
| * Use the [Oxford comma](https://en.wikipedia.org/wiki/Serial_comma) for coordinating conjunctions (C, C++__,__ and D) |
There was a problem hiding this comment.
Remind me again what are the double underscores about?
There was a problem hiding this comment.
Ah you are emphasizing the comma. :) All good.
There was a problem hiding this comment.
Ah you are emphasizing the comma. :) All good.
Yep ;-)
For the future: GitHub also allows to directly preview Markdown. Just click on the "View" link (top right).
There was a problem hiding this comment.
The reason it confused me is because I thought I was looking at a ddoc file. 😄
|
LGTM. |
|
I feel like this has gotten in way too quickly.
I think this should be reverted. Feel free to put this on the wiki on a linkable page, though. |
|
Yah this doesn't quite add a lot of value yet. It would be useful to initiate it as a wiki page and merge it when it gets more significant. |
|
@CyberShadow: From that perspective (the link on PR/issue creation), the whole file should be scrapped, though, and replaced with a short bullet list of important things to consider (links to style, our processes, …). |
|
Ok we could move it to the wiki. I'll revert it for now. |
Yep, that's just what I said here: dlang/phobos#4585 (comment) |
6 participants
As proposed on #1401, here's a proposal for a small writing guide to clarify common rules for contributors.
CC @AndrejMitrovic