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
| 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? |