Documentation style guide
This style guide provides guidelines to ensure that the documentation for this project is consistent, clear, and easy to follow. It standardizes aspects like phrasing, formatting, tone, and structure across all documentation.
I appreciate all contributions to the documentation—whether it's fixing a typo, adding new content, or writing an entirely new topic. To help me review and merge your contributions more efficiently, please follow the writing documentation guidelines. If you notice any inconsistencies, feel free to open an Issue or submit a Pull Request to fix them.
- General style guidelines
- Terminology
- Writing style
- Word choices
- Formatting guidelines
- Component-based formatting (if applicable)
- Error message formatting and troubleshooting
- Accessibility best practices
- Notes and warnings
General style guidelines
Logical order
- Documentation should be structured to follow the natural order of tasks or concepts, making it easier for users to understand and follow. Organize sections in a manner that reflects a logical workflow or a progressive understanding of a topic.
- When writing procedural documentation (how-to guides), the steps should follow the actual workflow, whether it involves Command Line Interface (CLI) commands, editing configuration files, or interacting with a Web UI. Specify the exact commands, file paths, or UI elements to interact with, and present them in the order they are encountered.
Headings
Use headings (sub-titles) to break up large blocks of text, making it easier for users to navigate the content and find specific sections quickly.
Look and feel of the docs
In general, the visual aesthetic of the technical documentation is intended to be lean and clean. Both the content
(shorter sentences, concise instructions, etc.) and the layout should strive for a clean, uncluttered look, with
restrained use of colors and large callouts. The colors used for :::info
and :::warning
callouts (typically light
blue and light yellow based on rendering engines) should be reserved for those purposes.
Cross-references
When linking to other documents within the /docs
site, use relative paths.
- Good:
[Link text](./path/to/document.md)
- Bad:
[Link text](/docs/path/to/document.md)
(avoid root-relative paths if simple relative paths work) - Bad:
[Link text](https://your-site.com/docs/path/to/document.md)
(avoid absolute URLs for internal links)
Example:
For more details on contributing documentation, see my guidelines for writing documentation.
Relative vs. absolute paths
Use relative paths when linking to other documentation files within this repository (e.g.,
[Link text](./another-doc.md)
). This ensures links remain valid if the documentation structure is hosted or moved. If
linking to an external resource or a different repository, use an absolute path.
Markdown file type
The standard file type for documentation is .md
. Use .mdx
only if advanced features requiring React components (like
interactive elements provided by a static site generator such as Docusaurus) are necessary. For this project, .md
is
typically sufficient.
OS-agnostic, clarify where needed
Strive to write procedural documentation generically enough that it does not assume or force a specific client operating
system (e.g., for running kubectl
or ssh
). If OS-specific instructions are necessary (e.g., different shell commands
for Windows vs. Linux), clearly label them or consider using tabs if the rendering engine supports them (an advanced
.mdx
feature).
Terminology
Industry terms and technology names
- When referring to external tools, services, or industry terms (e.g., Kubernetes, Docker, Git, YAML, OAuth, SAML), always use the exact capitalization and naming conventions that the product or standard uses. Refer to their official websites or documentation for proper formatting.
- Avoid abbreviations unless they are well-known and widely recognized within the context of this project (e.g., K8s for Kubernetes, VM for Virtual Machine, CI/CD).
- If an acronym is used less frequently or might be ambiguous, spell out its full meaning upon first mention, followed by the acronym in parentheses. For instance, "Persistent Volume Claim (PVC)."
Writing style
Tone
The tone of the documentation should be friendly but professional. It should be approachable and helpful, yet not overly
casual. When appropriate, address the reader directly using second-person pronouns (e.g., "Next, you need to configure
the ConfigMap
.").
Language
The documentation uses American English spelling conventions (e.g., "customize" instead of "customise," "initialize" instead of "initialise").
Voice
Use active voice and present tense for clear, direct communication.
- DON'T: "The ArgoCD Application will be synchronized by the controller."
- DO: "The ArgoCD controller synchronizes the Application." or "ArgoCD synchronizes the Application."
User-friendly phrasing
Avoid phrasing that might seem to blame the user for errors or misunderstandings. Be objective and polite when providing instructions or troubleshooting advice.
- DON'T: "You failed to set the correct replica count."
- DO: "Ensure that the replica count is set to the desired value. An incorrect replica count might lead to..."
Punctuation
Strive for clarity in punctuation. Use commas to separate clauses or items in a list and to improve readability. Please do use the Oxford comma (e.g., "networking, storage, and compute resources").
Capitalization
Titles and headers
Titles and headers (H1, H2, H3, etc.) should follow sentence case capitalization. This means only the first word and
proper nouns (like Kubernetes, ArgoCD, Talos, Proxmox, Bitwarden, names of specific scripts or files like
argocd-bootstrap.tf
) are capitalized.
Following a colon
Whether to capitalize after a colon depends on the context. Typically, do not capitalize the first word after a colon unless it's a proper noun or the start of a complete sentence. If the colon introduces a list of items that are not complete sentences, do not capitalize the first word of each item unless it's a proper noun. In headings and titles, if a colon is used, the first word after the colon should generally be capitalized if it begins a distinct conceptual part of the title.
Word choices
"May" versus "Might" versus "Can"
-
Typically, avoid using "may" in technical writing, as it can imply permission rather than capability. Instead, use "can" to suggest possibility or ability.
-
"Might" should be used to indicate that something could happen under certain conditions, but it implies a degree of unpredictability. Use it sparingly.
- DON'T: "You may use a
NetworkPolicy
to restrict traffic." - DO: "You can use a
NetworkPolicy
to restrict traffic." - DO: "The pod might enter a
CrashLoopBackOff
state if the configuration is incorrect."
- DON'T: "You may use a
"Login", "Log in", and "Log in to"
- As a noun or adjective, use login (e.g., "The ArgoCD login page," "login credentials").
- As a verb, use log in (e.g., "You will need to log in to the Grafana UI.").
- As a verb followed by the preposition "to," use log in to (e.g., "Log in to the Proxmox server.").
Use "that" as a conjunction
It's often good practice to use "that" as a conjunction to introduce a dependent clause, as it can improve clarity, especially for non-native English speakers and automated translation tools.
- DO: "Ensure that the
kubeconfig
file has the correct permissions." - DON'T: "Ensure the
kubeconfig
file has the correct permissions." (While not strictly incorrect, the former can be clearer).
"which" vs "that"
A common guideline:
- Use "that" for restrictive clauses (clauses essential to the meaning of the sentence and not set off by commas).
- Use "which" for non-restrictive clauses (clauses that add extra information and are usually set off by commas).
For more information, see Grammarly's explanation.
"since" (time-based) vs "because" (causal)
- Use "because" when indicating a cause or reason ("The pod failed because the image was not found.").
- Use "since" primarily for time-based references ("The cluster has been stable since the last upgrade."). Avoid using "since" to mean "because."
Avoid using "once" (numeric) to mean "after" (time-based)
When writing procedural steps, avoid starting a step with "Once..." to mean "After...".
- DON'T: "Once the script completes, check the logs."
- DO: "After the script completes, check the logs." or "After you have run the script, check the logs."
Formatting guidelines
Fonts and font styling
- When referring to general system components (e.g., "the GitOps workflow," "the storage solution"), do not use special formatting or capitalization unless it's a proper noun. Link to relevant documentation when possible.
- When referring to specific tools or technologies by name (e.g., ArgoCD, Kustomize, Longhorn), use their official capitalization.
- Use bold to highlight:
- UI elements if described (e.g., "Save button," "Applications tab in ArgoCD UI).
- Key actions in instructions (e.g., "Execute the following command:").
- Important terms or parameters being defined or emphasized for the first time.
- Use italic for:
- Emphasis, but sparingly, to avoid overuse. For example, you can use italics for important terms or concepts on first mention in a section.
- Filenames or paths when mentioned in a sentence but not as a literal path to be copied (though backticks are often preferred for paths).
- Use
code formatting
(backticks) for:- Commands (e.g.,
kubectl get pods -n argocd
). - File paths and directory names (e.g.,
/k8s/infrastructure/networking/
,kustomization.yaml
). - Inline code snippets, parameter names, keys in YAML/JSON (e.g.,
spec.replicas
,targetRevision: main
). - Environment variable names (e.g.,
KUBECONFIG
).
- Commands (e.g.,
- When handling URLs:
- For URLs that are literal values in configurations or examples, or if they contain placeholders, use
code formatting
and enclose any variables inside angle brackets (< >
) to clearly indicate that these are placeholders that require user input. Example:https://<your-argocd-server>/api/v1
- When mentioning general URLs in explanatory text or within procedural instructions as a reference, omit code formatting. For instance: "You can find more details on the official Kubernetes documentation site at https://kubernetes.io."
- For URLs that are literal values in configurations or examples, or if they contain placeholders, use
Examples
When providing examples, such as code snippets or configuration blocks:
Example:
This Kustomization manifest demonstrates how to include resources:
# kustomization.yaml
apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization
resources:
- deployment.yaml
- service.yaml
namespace: my-app
Code blocks
Use fenced code blocks (triple backticks) for multi-line code, configuration examples, or shell commands. Specify the language for syntax highlighting.
```yaml showLineNumbers {5} title="/k8s/applications/example-app/deployment.yaml"
apiVersion: apps/v1
kind: Deployment
metadata:
name: example-app-deployment
spec:
replicas: 2 # highlight-this-line
selector:
matchLabels:
app: example-app
template:
metadata:
labels:
app: example-app
spec:
containers:
- name: app-container
image: 'your-app-image:{{ .Values.appVersion }}'
ports:
- containerPort: 80
```
```yaml
defines the language (e.g.,yaml
,bash
,terraform
,json
,text
).- Optional configurations (depending on your Markdown renderer, e.g., Docusaurus):
showLineNumbers
: Enables line numbering.title="<path/to/file_or_description>"
: Defines a title displayed above the code block.{N}
or{N-M}
: Defines line number(s) to be highlighted.- Comments like
// highlight-next-line
,// highlight-start
,// highlight-end
can also be used for highlighting within the code block if supported.
Component-based formatting (if applicable)
This section would cover the usage of special components (like React components in MDX) if the documentation system
supports and uses them. For standard Markdown (.md
) files, this is generally not applicable.
Tabs for multiple configurations (MDX example)
If using an MDX-based system, you can use tabs to display different configurations or command sequences side-by-side.
Example (conceptual, for MDX):
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
<Tabs
defaultValue="linux"
values={[
{ label: 'Linux/macOS', value: 'linux' },
{ label: 'Windows (PowerShell)', value: 'windows' },
]}
>
<TabItem value="linux">
<pre>
<code className="language-bash">export MY_VAR="value" ./run_script.sh</code>
</pre>
</TabItem>
<TabItem value="windows">
<pre>
<code className="language-powershell">$env:MY_VAR="value" .\run_script.ps1</code>
</pre>
</TabItem>
</Tabs>;
This project currently uses plain Markdown, so these advanced tab features are not directly applicable unless the rendering pipeline includes such capabilities.
Error message formatting and troubleshooting
When documenting error messages and their solutions:
- Display the error message clearly, preferably in a code block.
- Explain possible causes of the error.
- Offer concrete solutions or troubleshooting steps.
Example:
-
Error message:
Error from server (NotFound): deployments.apps "my-nginx" not found
-
Possible causes:
- The deployment
my-nginx
does not exist in the current namespace. - A typo in the deployment name.
- You are targeting the wrong namespace (
kubectl config current-context
orkubens
can verify).
- The deployment
-
Solution:
-
Verify the deployment name and the namespace you are operating in.
-
List deployments in the namespace to check for existence:
kubectl get deployments -n <your-namespace>
-
If the deployment should exist, check ArgoCD sync status or application logs for deployment errors.
-
Accessibility best practices
- Avoid using color as the sole method of conveying information (e.g., "The failing pods are shown in red"). Instead, use descriptive text.
- Provide descriptive link text. Avoid generic terms like "Click here." Be specific about the destination or purpose
of the link.
- DON'T: "Click here for details."
- DO: "For more details, see the Kubernetes manifest validation guide."
Notes and warnings
Use admonitions to draw attention to important pieces of information.
Notes are for supplementary information, tips, or elaborations. Format using:
:::info[This is an informational note. It provides additional context or a helpful tip related to the main text. :::]
Warnings are for critical information that users must be aware of to avoid errors, data loss, or security risks. Format using:
:::warning[Exercise caution when modifying this configuration, as incorrect changes can lead to system instability. :::]