Skip to content

Commit 51ebb0c

Browse files
danbarrdanbarr
authored
Add style guide and update README (#51)
1 parent a1c8dc3 commit 51ebb0c

File tree

2 files changed

+289
-7
lines changed

2 files changed

+289
-7
lines changed

‎README.md

+43-7
Original file line numberDiff line numberDiff line change
@@ -1,31 +1,67 @@
1-
# CodeGate docs
1+
# CodeGate docs <!-- omit in toc -->
22

33
This repository contains the public-facing docs for CodeGate, hosted at
44
[https://docs.codegate.ai](https://docs.codegate.ai).
55

6-
## Local Development
6+
- [Contributing to docs](#contributing-to-docs)
7+
- [Local development](#local-development)
8+
- [Formatting](#formatting)
9+
- [Building the site](#building-the-site)
10+
- [Deployment](#deployment)
11+
- [About](#about)
12+
13+
## Contributing to docs
14+
15+
We welcome contributions to the CodeGate documentation - if you find something
16+
missing, wrong, or unclear, please let us know via an issue or open a PR!
17+
18+
Please review the [style guide](./STYLE-GUIDE.md) for help with voice, tone, and
19+
formatting.
20+
21+
## Local development
722

823
```bash
924
npm install
1025
npm run start
1126
```
1227

13-
This command starts a local development server and opens up a browser window.
14-
Most changes are reflected live without having to restart the server.
28+
This command starts a local development server on port 3000 and opens a browser
29+
window to <http://localhost:3000>. Most changes are reflected live without
30+
having to restart the server.
31+
32+
## Formatting
33+
34+
We use a combination of Prettier, markdownlint, and ESLint to normalize
35+
formatting and syntax. Before you submit a PR, please check for issues:
36+
37+
```bash
38+
npm run prettier
39+
npm run markdownlint
40+
npm run eslint
41+
```
42+
43+
To automatically fix issues:
44+
45+
```bash
46+
npm run prettier:fix
47+
npm run markdownlint:fix
48+
npm run eslint:fix
49+
```
1550

16-
## Build
51+
## Building the site
1752

1853
```bash
1954
npm run build
2055
```
2156

22-
This command generates static content into the `build` directory.
57+
This command generates static content into the `build` directory. It also checks
58+
for broken links, so it's recommended to run this before submitting a PR.
2359

2460
## Deployment
2561

2662
The `docs.codegate.ai` site is published using Vercel. Automatic previews for
2763
branches and pull requests are enabled. The production site is published from
28-
main.
64+
the `main` branch.
2965

3066
## About
3167

‎STYLE-GUIDE.md

+246
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,246 @@
1+
# Style guide for CodeGate docs <!-- omit in toc -->
2+
3+
This style guide is a reference for anyone who contributes to the user-facing
4+
CodeGate docs contained in this repository. By adhering to these guidelines, we
5+
aim to deliver clear, concise, and valuable information to CodeGate users.
6+
7+
## Contents <!-- omit in toc -->
8+
9+
- [Writing style](#writing-style)
10+
- [Language](#language)
11+
- [Tone and voice](#tone-and-voice)
12+
- [Active voice](#active-voice)
13+
- [Speak to the reader](#speak-to-the-reader)
14+
- [Capitalization](#capitalization)
15+
- [Punctuation](#punctuation)
16+
- [Links](#links)
17+
- [Formatting](#formatting)
18+
- [Screenshots and images](#screenshots-and-images)
19+
- [Markdown style](#markdown-style)
20+
- [Word list \& glossary](#word-list--glossary)
21+
- [Products/brands](#productsbrands)
22+
23+
## Writing style
24+
25+
This list is not exhaustive, it is intended to reflect the most common and
26+
important style elements. For a more comprehensive guide that aligns with our
27+
style goals, or if you need more details about any of these points, refer to the
28+
[Google developer documentation style guide](https://developers.google.com/style).
29+
30+
### Language
31+
32+
The project's official language is **US English**.
33+
34+
### Tone and voice
35+
36+
Strive for a casual and conversational tone without becoming overly informal. We
37+
aim to be friendly and relatable while retaining credibility and professionalism
38+
– approachable yet polished.
39+
40+
Avoid slang and colloquial expressions. Use clear, straightforward language and
41+
avoid overly complex jargon to make content accessible to a wide audience.
42+
43+
#### Active voice
44+
45+
Use **active voice** instead of passive voice. Active voice emphasizes the
46+
subject performing the action, making the writing more direct and engaging.
47+
Passive voice focuses on the recipient of the action rather than the actor,
48+
often resulting in unclear sentences and misinterpretation of responsibility.
49+
50+
:white_check_mark: Yes: Replace `docker` with `podman` in all commands if you
51+
use Podman.\
52+
:x: No: `docker` should be replaced with `podman` in all commands if Podman is
53+
used.
54+
55+
#### Speak to the reader
56+
57+
Address the reader using the **second person** ("you", "your"). Avoid the first
58+
person ("we", "our") and third person ("the user", "a developer").
59+
60+
### Capitalization
61+
62+
Capitalize **proper nouns** like names, companies, and products. Generally,
63+
**don't** capitalize features or generic terms. For non-CodeGate terms, follow
64+
the norms of the third-party project/company (ex: npm is stylized in lowercase,
65+
even when it begins a sentence).
66+
67+
:white_check_mark: Yes: CodeGate includes a web dashboard that lets you view...\
68+
:x: No: CodeGate includes a Web Dashboard that lets you view...
69+
70+
Use **sentence case** in titles and headings.
71+
72+
:white_check_mark: Yes: Alternative run commands\
73+
:x: No: Alternative Run Commands
74+
75+
Use `ALL_CAPS` to indicate placeholder text/parameters, where the reader is
76+
expected to change a value.
77+
78+
### Punctuation
79+
80+
**Oxford comma**: use the Oxford comma (aka serial commas) when listing items in
81+
a series.
82+
83+
:white_check_mark: Yes: CodeGate scans direct, transitive, and development
84+
dependencies.\
85+
:x: No: CodeGate scans direct, transitive and development dependencies.
86+
87+
**Quotation marks**: use straight double quotes and apostrophes, not "fancy
88+
quotes" or "smart quotes" (the default in document editors like Word/Docs). This
89+
is especially important in code examples where smart quotes often cause syntax
90+
errors.
91+
92+
Tip: if you are drafting in Google Docs, disable the "Use smart quotes" setting
93+
in the Tools → Preferences menu to avoid inadvertently copying smart quotes into
94+
Markdown or other code.
95+
96+
### Links
97+
98+
Use descriptive link text. Besides providing clear context to the reader, this
99+
improves accessibility for screen readers.
100+
101+
:white_check_mark: Yes: For more information, see
102+
[Purpose and scope](?tab=t.0#heading=h.qaqvuha5efk).\
103+
:x: No: For more information, see
104+
[this section](?tab=t.0#heading=h.qaqvuha5efk).
105+
106+
Note on capitalization: when referencing other docs/headings by title, use
107+
sentence case so the reference matches the corresponding title or heading.
108+
109+
### Formatting
110+
111+
**Bold**: use when referring to UI elements; prefer bold over quotes. For
112+
example: Click **Add Rule** and select the rule you want to add to the profile.
113+
114+
**Italics**: emphasize particular words or phrases, such as when
115+
introducing/defining a term. For example: A _profile_ defines which security
116+
policies apply to your software supply chain.
117+
118+
**Underscore**: do not use; reserved for links.
119+
120+
**Code**: use a `monospaced font` for inline code or commands, code blocks, user
121+
input, filenames, method/class names, and console output.
122+
123+
## Screenshots and images
124+
125+
Considerations for screenshots and other images:
126+
127+
- Don't over-use screenshots:
128+
- Screenshots are useful for complex UIs or to point out specific elements
129+
that are otherwise hard to describe with text. But for example, an input
130+
form doesn't need a screenshot when text can just as easily list the fields
131+
and their purpose.
132+
- Screenshots age rapidly.
133+
- Too many screenshots can become visually overwhelming and interrupt the flow
134+
of documentation.
135+
- Don't use images of text, code samples, or terminal output. Use actual text so
136+
readers can copy/paste and find the contents via search engines.
137+
- Use alt text to describe images for readers using screen readers and to assist
138+
search engines.
139+
- Be consistent when taking screenshots - use the same OS if possible (macOS has
140+
been used in CodeGate docs to date) and zoom level (ex: zoom twice in VS Code,
141+
125% in browsers).
142+
- Crop screenshots to the relevant portion of the interface.
143+
- Use the primary brand color (`#5058ff`) for annotations like callouts and
144+
highlight boxes.
145+
146+
## Markdown style
147+
148+
Just like a consistent writing style is critical to clarity and messaging,
149+
consistent formatting and syntax are needed to ensure the maintainability of
150+
Markdown-based documentation.
151+
152+
We generally adopt the
153+
[Google Markdown style guide](https://google.github.io/styleguide/docguide/style.html),
154+
which is well-aligned with default settings in formatting tools like Prettier
155+
and `markdownlint`.
156+
157+
Our preferred style elements include:
158+
159+
- Headings: use "ATX-style" headings (hash marks - `#` for Heading 1, `##` for
160+
Heading 2, and so on); use unique headings within a document
161+
- Unordered lists: use hyphens (`-`), not asterisks (`*`)
162+
- Ordered lists: use lazy numbering (`1.` for every item and let Markdown render
163+
the final order – this is more maintainable when inserting new items)
164+
- Note: this is a "soft" recommendation. It is also intended only for Markdown
165+
documents that are read through a rendering engine. If the Markdown will be
166+
consumed in raw form, use real numbering.
167+
- Code blocks: use fenced code blocks (` ``` ` to begin/end) and explicitly
168+
declare the language, like ` ```python ` or ` ```plain `
169+
- Add blank lines around headings, lists, and code blocks
170+
- No trailing whitespace on lines
171+
- Use the `\` character at the end of a line for a single-line break, not the
172+
two-space syntax which is easy to miss
173+
- Line limit: wrap lines at 80 characters; exceptions for links, tables,
174+
headings, and code blocks
175+
176+
Specific guidelines for Docusaurus:
177+
178+
- Heading 1 is reserved for the page title, typically defined in the Markdown
179+
front matter section. Sections within a page begin with Heading 2 (`##`).
180+
[Reference](https://docusaurus.io/docs/markdown-features/toc)
181+
- Use relative file links (with .md/.mdx extensions) when referring to other
182+
pages. [Reference](https://docusaurus.io/docs/markdown-features/links)
183+
- Use the .mdx extension for pages containing JSX includes. Docusaurus v3
184+
currently runs all .md and .mdx files through an MDX parser but this will
185+
change in a future version.
186+
[Reference](https://docusaurus.io/docs/migration/v3#using-the-mdx-extension)
187+
- Use the front matter section on all pages. At a minimum, set the `title` (this
188+
is rendered into the page as an H1) and a short `description`.
189+
[Reference](https://docusaurus.io/docs/api/plugins/@docusaurus/plugin-content-docs#markdown-front-matter)
190+
- Place images in `static/img` using WebP, PNG, or SVG format.
191+
- Use the
192+
[`ThemedImage` component](https://docusaurus.io/docs/markdown-features/assets#themed-images)
193+
to provide both light and dark mode screenshots for apps/UIs that support
194+
both.
195+
196+
## Word list & glossary
197+
198+
Common terms used in CodeGate content:
199+
200+
**CodeGate**: this project! It's written bi-capitalized as one word (not
201+
"Codegate" or "Code Gate").
202+
203+
**open source**: we prefer using two words over the hyphenated form (not
204+
"open-source"). It's not a proper noun, so don't capitalize unless it starts a
205+
sentence.
206+
207+
**OSS**: abbreviation for "open source software".
208+
209+
**Stacklok**: the company that makes CodeGate.
210+
211+
### Products/brands
212+
213+
**Continue** - an open source AI coding assistant for IDEs that connects to many
214+
model providers. It's written as just "Continue" (not "Continue.dev", which is
215+
their website).
216+
217+
**Copilot** - GitHub's AI coding assistant. It's written with only a leading
218+
capital (not "CoPilot").
219+
220+
**Git**: the most popular distributed version control system. It underpins most
221+
commercial VCS offerings like GitHub, Bitbucket, and GitLab. Unless specifically
222+
referring to the `git` command line tool, it's a proper noun and should be
223+
capitalized.
224+
225+
**GitHub**: the most popular source code hosting provider, especially for open
226+
source. It's written bi-capitalized as one word (not "Git Hub" or "Github").
227+
228+
**JetBrains**: a company that makes IDEs for many languages, including IntelliJ
229+
IDEA, PyCharm, GoLand, and more. It's written bi-capitalized as one word (not
230+
"Jet Brains" or "Jetbrains"). It's proper to reference a specific JetBrains IDE
231+
when needed, or simply refer to "all JetBrains IDEs".
232+
233+
**npm**: the registry for JavaScript packages (the "npm registry"), and the
234+
default package manager for JavaScript. Since it's both the registry _and_ the
235+
package manager, it may be useful to disambiguate "the npm registry". It's not
236+
an abbreviation, so it's not capitalized; it's written all lowercase (not
237+
"NPM").
238+
239+
**Visual Studio Code**: a very popular free integrated development environment
240+
(IDE) from Microsoft. Per Microsoft's
241+
[brand guidelines](https://code.visualstudio.com/brand#brand-name), use the full
242+
"Visual Studio Code" name the first time you reference it. "VS Code" is an
243+
acceptable short form after the first reference. It's written as two words and
244+
there are no other abbreviations/acronyms (not "VSCode", "VSC", or just "Code").
245+
246+
<!-- markdownlint-disable-file MD044 -->

0 commit comments

Comments
 (0)