Did a general sweep for style, grammar, and voice.
I roughly base my suggestions on the Google Developer style guide which is a pretty standard practice. They have a lot of specific usage and grammar rules, but also flexibility to develop our own voice. Happy to talk through any specifics, and there were a couple places I was taking a guess about some missing detail that will need to be checked for technical accuracy.
Sometimes folks ask me to explain the edits I made so here's some consistent conventions I noticed I was adding:
Docs tend to be as active voice as possible and try to avoid using pronouns like "we", "us", and "our." I think this is totally a case by case thing. Dev advocacy has a voice similar to a teacher, so they use "we"/"our", while marketing materials aim for friendly amicability, so they use them as well. Traditional docs typically have a drier tone and sometimes have legal restrictions around the claims they can make regarding recommendations, so it's often avoided entirely or used sparingly. There's some flexibility we have here that traditional product docs might not.
It's risky to emphasize text with " " instead of formatting. Sometimes " " implies to users that the thing being emphasized is supposed to be a string or a literal, when all the intention in writing the sentence was to make emphasize a label. Instead, it's more conventional to use:
Italics for introducing a new term or label for a technical concept
code/<pre> for anything that gets entered in a config or executable file, programmatic in general, specific URLs, or example URL's.
bold for any titles, labels, or intractable elements like a button, radio, or dropdown. They are the things you click or the headers you scan for when searching through a UI.
In docs, if a user needs to take an action in a specific context, for example if they need to change from OpenAI back to their local terminal, it's best to use a sentence structure where we have [Describe context], [describe action] [describe outcome]. Or [Describe outcome], [Describe context], [describe action]. Otherwise, you risk someone executing things in the wrong environment or looking in the wrong place for something.
Docs use headers, bullets, and indentations in a very prescriptive way. There's a few places where everything was aligned at the same bullet/ ordered list level, instead of indenting or showing parent/child relationship in some way. However I didn't have time to get my local build working, just had a chance to do the edits. We need to check my changes in a preview first to make sure the formatting is rendering as expected.
Did a general sweep for style, grammar, and voice.
I roughly base my suggestions on the Google Developer style guide which is a pretty standard practice. They have a lot of specific usage and grammar rules, but also flexibility to develop our own voice. Happy to talk through any specifics, and there were a couple places I was taking a guess about some missing detail that will need to be checked for technical accuracy.
Sometimes folks ask me to explain the edits I made so here's some consistent conventions I noticed I was adding:
Docs tend to be as active voice as possible and try to avoid using pronouns like "we", "us", and "our." I think this is totally a case by case thing. Dev advocacy has a voice similar to a teacher, so they use "we"/"our", while marketing materials aim for friendly amicability, so they use them as well. Traditional docs typically have a drier tone and sometimes have legal restrictions around the claims they can make regarding recommendations, so it's often avoided entirely or used sparingly. There's some flexibility we have here that traditional product docs might not.
It's risky to emphasize text with
" "instead of formatting. Sometimes" "implies to users that the thing being emphasized is supposed to be a string or a literal, when all the intention in writing the sentence was to make emphasize a label. Instead, it's more conventional to use:code/<pre>for anything that gets entered in a config or executable file, programmatic in general, specific URLs, or example URL's.In docs, if a user needs to take an action in a specific context, for example if they need to change from OpenAI back to their local terminal, it's best to use a sentence structure where we have [Describe context], [describe action] [describe outcome]. Or [Describe outcome], [Describe context], [describe action]. Otherwise, you risk someone executing things in the wrong environment or looking in the wrong place for something.
Docs use headers, bullets, and indentations in a very prescriptive way. There's a few places where everything was aligned at the same bullet/ ordered list level, instead of indenting or showing parent/child relationship in some way. However I didn't have time to get my local build working, just had a chance to do the edits. We need to check my changes in a preview first to make sure the formatting is rendering as expected.
Remaining review items for follow-up PR: