@devries-cameron20 / composio Mirror · read-only
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 07:15 UTC

next
md 75 lines 5.58 KB
Rendered Raw
1 # Style Guide
2
3 Apply every rule below while drafting. Each rule is an imperative followed by a real Modal example as evidence (this guide is derived from Modal's documentation voice).
4
5 ## Voice & Tone
6
7 - **Address the reader as "you"; speak directly.** Don't hide behind "the user" or "one."
8 > "Modal's goal is to make running code in the cloud feel like you're running code locally."
9 - **Be confident and plain, not hedgy or salesy.** State what's true. Lead with the benefit, not the disclaimer.
10 > "Modal makes it trivially easy to scale compute across thousands of containers."
11 - **Reassure when something is automatic.** Tell the reader what they _don't_ have to worry about.
12 > "For the most part, scaling out will happen automatically, and you won't need to think about it."
13 - **Explain the "why" before prescribing the "how."** Motivate the solution, then give it.
14 - **Use contractions naturally** ("you don't," "won't," "it's"). They keep the tone human.
15 - **Allow occasional warmth and personality** ("That's it!", "Take a breath of fresh air"), sparingly, never goofy.
16
17 ## Structure
18
19 - **Open by defining the concept or stating the benefit in one sentence**, then elaborate. No throat-clearing.
20 > "An `App` represents an application running on Modal. It groups one or more Functions for atomic deployment and acts as a shared namespace."
21 - **Order content as concept → simple example → advanced cases → gotchas.** Progressive disclosure.
22 - **Lead with a minimal runnable example early**, then explain what just happened.
23 - **Keep paragraphs short.** Break dense information into bullet lists and numbered steps.
24 - **Use signposting transitions** to mark explanatory shifts: "What just happened?", "But why does this matter?", "Now, as before, …".
25 - **Mix sentence lengths.** Short declarative sentences carry the load; longer ones add necessary nuance.
26 > "The timeout duration is a measure of a Function's _execution_ time. It does not include scheduling time or any other period besides the time your code is executing in Modal."
27
28 ## Terminology
29
30 - **Capitalize your product's core nouns as proper concepts** the way Modal capitalizes App, Function, Image, Volume, Secret, Sandbox, Cls. Capitalize a noun when it names the product, lowercase for the generic idea.
31 - **Name the product consistently**; never "the Modal platform" filler.
32 - **Prefer precise technical terms over hand-waving**: "cold start," "autoscaler," "ephemeral," "atomic deployment," "warm pool," "scaledown window." Introduce a term in context the first time, then use it freely.
33 > "This is known as a _cold start_, and it is often associated with higher latency."
34 - **Avoid marketing fluff and vague intensifiers** ("seamlessly," "powerful," "robust," "cutting-edge"). If a thing is easy, show it being easy.
35 - **Use analogies to ground unfamiliar concepts**, then move on.
36 > "Containers are like light-weight virtual machines."
37
38 ## Punctuation
39
40 - **Do not use em-dashes.** Rewrite the sentence with a period, comma, colon, or parentheses instead. This is a hard rule; remove every em-dash before you ship. (This overrides Modal's softer "em-dashes for genuine asides only" guidance: em-dashes are banned here.)
41 - **Use the Oxford comma.**
42 - **Use backticks for every code identifier, command, parameter, path, and filename**: `@app.function()`, `modal deploy`, `scaledown_window`, `/gpu-glossary/`.
43 - **Use italics for fine distinctions and negation**, not for general emphasis.
44 > "This automatic upgrade does _not_ change the cost of the GPU."
45 - **Capitalize acronyms and hardware names** as conventional: GPU, ASGI, A100, H100.
46
47 ## Code examples
48
49 - **Show a complete, runnable snippet first**: imports, decorator, function, not a fragment the reader can't paste.
50 - **Keep examples minimal.** Use simple names (`f`, `app`) and elide irrelevant bodies with `...`.
51 - **Show the decorator pattern Modal uses** (`@app.function()`, `@app.cls()`) and method chaining for Images.
52 - **Put comments only where behavior is non-obvious**; let clean code speak otherwise. Show expected output inline where it teaches something (`# 42`).
53 - **Show real CLI invocation forms** with realistic prompts: `$ ` or `%` for shell, `>>>` for the Python REPL.
54 > "modal run script.py::app.f"
55 - **When a flag is a footgun, say so right after the example.**
56 > "Remember to remove `force_build=True` after you've rebuilt the Image, or it will rebuild every time you run your code."
57
58 ## Formatting
59
60 - **Use heading case consistently within a doc.** Modal leans toward sentence case for conceptual guides ("How do Web Functions run in the cloud?", "Scaling out") and title case for reference-style headings ("Volume commits and reloads"). Pick one convention per page and don't drift.
61 - **Prefer descriptive, specific headings** over generic ones: "Entrypoints for ephemeral Apps," not "Entrypoints."
62 - **Use callouts for warnings, notes, gated features, and beta status** rather than burying them in prose.
63 > "Deployment rollbacks are available on the Team and Enterprise plans."
64 - **Correct gently with a "Note that …" or "Gotchas" aside** instead of stern warnings.
65 - **Link with descriptive anchor text**, embedded naturally in the sentence, never a bare URL or "click here."
66 - **Bold key concepts on first definition**, then stop bolding them.
67
68 ## Quick self-check while drafting
69
70 - Did I open with the concept or benefit in the first sentence?
71 - Is there a runnable example near the top?
72 - Am I saying "you," not "the user"?
73 - Did I remove every em-dash?
74 - Did I cut every "seamlessly," "powerful," and other vague intensifier?
75 - Are all code identifiers in backticks and core nouns (App, Function, Volume) capitalized?