Add a style guide #5209
Add a style guide #5209
Conversation
zanieb
added
documentation
zanieb
force-pushed
the
zb/style
branch
3 times, most recently
from
afdc109
to
0a2986a
Compare
| ## General | ||
|
|
||
| 1. Use of "e.g." and "i.e." should always be wrapped in commas, e.g., as shown here. | ||
| 1. Em-dashes are okay, but not recommended when using monospace fonts. Use "—", not "--" or "-". |
There was a problem hiding this comment.
Could we stay with ascii in input files where possible?
There was a problem hiding this comment.
Our plain text files, e.g. markdown files, as opposed to rich output files such as html. For example, latex has \textemdash and converts that to a real em dash in the pdf output.
There was a problem hiding this comment.
In documentation? I have a pretty strong preference for being able to use em dashes in the markdown.
There was a problem hiding this comment.
Non-unicode characters are a nuisance to enter, esp. across keyboard layouts, and when they look like an ascii characters they tend to cause unnecessary debugging
| 1. Do not use the `bash` syntax when displaying command output. | ||
| 1. Command output should rarely be included — it's hard to keep up to date. | ||
|
|
||
| ## CLI |
There was a problem hiding this comment.
If we have an error message, are the hints before or after the error message? Do we include urls in messages? When do we (not) capitalize?
## Summary Per #5209, we only show periods in messages when the message itself spans more than a single sentence.
|
Let's send it — lots more to do here though. |
No description provided.