Add lots of docs, mostly best practices.#2
Conversation
content/docs/practices/alerting.md
Outdated
There was a problem hiding this comment.
Anyone set something like that up? That would be a great addition to the docs.
There was a problem hiding this comment.
Not that I'm aware of. Once one of us does it we should certainly contribute it back.
There was a problem hiding this comment.
Comma after "For example" (http://english.stackexchange.com/questions/132359/any-exception-with-commas-before-and-after-for-example).
I think for now should spell them "push gateway" and "alert manager" (My feeling is that if we're using these like descriptive words in normal English, they should be spelled as two words and lower-case.), though I don't feel strongly at all about that. Main thing is that we standardize and make things consistent.
There was a problem hiding this comment.
We're referring to our particular Alertmanager and PushGateway implementations, thus I think they're proper nouns and get capitals.
|
Beside the minor notes, really great documentations! Very useful and well written. 👍 |
brian-brazil
force-pushed
the
master
branch
6 times, most recently
from
cb0c182 to
ae064e0
Compare
There was a problem hiding this comment.
There are some extra words here: "in an during an outage"
|
Sorry, this is just the first iteration of comments. I simply don't have a lot of free-wheeling computer time at Congress... will try to get back to it ASAP. |
|
@juliusv I'm impressed by your proofreading skills :) |
content/docs/practices/alerting.md
Outdated
There was a problem hiding this comment.
I feel like there's too much "you want", "you should", etc. in this style.
Taking out the "you" in this concrete example could be done like: "Typically it makes sense to alert...".
Alternatives in other places could be to simply omit the "you should" sometimes and just leave it at the imperative form. E.g. below: "Only page on latency..."
content/docs/practices/alerting.md
Outdated
There was a problem hiding this comment.
s/You should//
s/allow/allow for/
s/accomodate/accommodate/
|
Ok, that was one more round of comments - more to follow when I find the time! |
Start out on the visualisation docs. Expand overview, remove federation as a feature we don't have that yet. Switch example variable to follow naming scheme.
|
I think that's all of your comments covered. Not using contractions feels very unnatural to me. |
|
@brian-brazil Thanks! Re-reading and then reading the second half now. I agree in some cases about the contractions. @opensourcegrrrl (our doc writer) has always told me to avoid them, but I'm not sure if we have to be so strict about it. |
|
As discussed on IRC, I'm going to merge this as-is now and send a followup PR with some changes later. Easier for everyone :) |
Add lots of docs, mostly best practices.
|
"Expand abbreviations, such as e.g., because they add complexity for non-native readers, are used inconsistently, and are unnecessary." http://infobits.eu/tech-doc/style-guide/ |
|
In an instance such as, "When doesn't it fit?", the emphasis should be on not, yet that part is contracted. "When does it not fit?" might be the clearer option. |
This introduces a lot of small followup changes to #2. Some things are clear right/wrong spelling/grammar issues, while others are a matter of style or taste. Except in extreme cases, I didn't reflow the text aggressively to a certain number of columns, in order to make it easier to spot differences. Let me know what you think.
This introduces a lot of small followup changes to #2. Some things are clear right/wrong spelling/grammar issues, while others are a matter of style or taste. Except in extreme cases, I didn't reflow the text aggressively to a certain number of columns, in order to make it easier to spot differences. Let me know what you think. Some reference links worth mentioning: Compound adjectives: http://www.grammar-monster.com/lessons/adjectives_compound_adjectives.htm Run-on sentences: http://grammar.ccc.commnet.edu/grammar/runons.htm General tech-writing style guide (which I haven't actually looked at much yet): http://infobits.eu/tech-doc/style-guide/
This introduces a lot of small followup changes to #2. Some things are clear right/wrong spelling/grammar issues, while others are a matter of style or taste. Except in extreme cases, I didn't reflow the text aggressively to a certain number of columns, in order to make it easier to spot differences. Let me know what you think. Some reference links worth mentioning: Compound adjectives: http://www.grammar-monster.com/lessons/adjectives_compound_adjectives.htm Run-on sentences: http://grammar.ccc.commnet.edu/grammar/runons.htm General tech-writing style guide (which I haven't actually looked at much yet): http://infobits.eu/tech-doc/style-guide/
4 participants
Start out on the visualisation docs.
Expand overview, remove federation as a feature we don't have that yet.
Switch example variable to follow naming scheme.