-
Notifications
You must be signed in to change notification settings - Fork 54
docs(agents): record W&B product and platform facts for style passes #2986
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
+11
−2
Merged
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit
Hold shift + click to select a range
95c7712
docs(agents): record W&B product and platform facts for style passes
johndmulhausen 60a2546
docs(agents): drop callout and keywords guidance
johndmulhausen f7ae3f9
docs(agents): name the web app W&B, not the W&B App
johndmulhausen 8165655
docs: restore product-naming facts pulled from style-guide skill
anastasiaguspan f57c281
Apply suggestion from @anastasiaguspan
anastasiaguspan 0ae2688
Apply suggestion from @anastasiaguspan
anastasiaguspan 7b11b32
Merge branch 'main' into docs/agents-md-product-conventions
mdlinville File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
|
|
@@ -85,7 +85,16 @@ To check or apply style, read the relevant pass file(s) and use them as guidance | |||||
| - **Python SDK functions**: Module-level functions in the Python SDK are listed in the [Global Functions overview](/models/ref/python/functions). | ||||||
| - **`.editorconfig`**: An `.editorconfig` file in the repository root enforces indentation and whitespace automatically. Most editors apply it with no configuration. If yours doesn't support it natively, install the EditorConfig plugin (https://editorconfig.org/#download). | ||||||
| - **Consistent language tab labels**: When an example offers multiple languages — in a `<CodeGroup>` or across `<Tab title="...">` blocks — label every tab with the same canonical name everywhere: `Python`, `TypeScript` (never `Typescript`), `Bash`. In a `<CodeGroup>`, give each fence a lowercase lexer **and** that canonical title (e.g. a `python` fence titled `Python`); never leave a language fence untitled. The reader's **Python/TypeScript** choice carries from page to page via `code-group-language-persist.js` (repo root), which matches those two labels case-insensitively — so inconsistent casing of them silently resets it. Other labels like `Bash` are only for in-page consistency and are intentionally not persisted across pages. Don't add a competing per-page persistence script. | ||||||
| - **ARIA chat examples**: When a task can be delegated to ARIA end-to-end in the W&B app, add a compact chat example as a third content modality alongside code examples and UI click sequences. Use **ARIA** as the public-facing product name in prose and in fence titles. | ||||||
| - **Company name**: W&B (not "Weights & Biases") in running text. | ||||||
| - **First mention pattern**: Use "W&B [Product]" on first mention of a product in a page, then drop "W&B" for later mentions — this is how Weave, Models, and Launch behave. Run, artifact, and report are looser: keeping "W&B" throughout (not just on first mention) is current usage too. Sweep is the exception that always drops it — see Sweeps below. | ||||||
| - **Product name capitalization**: Products stay capitalized on their own — W&B Weave → Weave, W&B Models → Models, W&B Launch → Launch. W&B artifact and W&B run are always lowercase ("an artifact", "a run"), matching how the API names these objects. | ||||||
| - **The web app is "W&B"** ("Weights & Biases" in full) — not the "W&B App". Now that a mobile app exists, "app" no longer identifies the web product. Name the interface itself the **W&B UI**, a component of W&B, when a sentence needs to distinguish it from the API or SDK. | ||||||
| - **W&B Python SDK**: The `wandb` package is the W&B Python SDK. Use "the W&B Python SDK (`wandb`)" as the full form and "the `wandb` library" as the short form. | ||||||
| - **Weave UI labels**: When one of these words names a tab, view, page, table, or panel in the Weave UI, it keeps its UI casing: Traces, Calls, Threads, Conversations, Spans, Signals, Agents, Scorers, Monitors, Evals, Models, Datasets, Prompts, Assets, Dashboard, Playground, Leaderboard. The same words as ordinary nouns in prose ("the calls in this trace") are lowercase throughout the docset — don't recapitalize them. | ||||||
| - **Project navigation**: The navigation inside a W&B project is the **project sidebar** (the **Weave project sidebar** in Weave docs), not the "left sidebar", "sidebar menu", or "left navigation". Bare "sidebar" is fine. This covers W&B's own in-project navigation only — leave third-party console steps (for example, the Microsoft Entra ID and Slack procedures under `platform/hosting/`), W&B organization- and team-level navigation, and `release-notes/` wording as written. | ||||||
|
Contributor
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
anastasiaguspan marked this conversation as resolved.
Outdated
|
||||||
| - **Sweeps**: W&B Sweeps is the product; an individual one is "a sweep", not "a W&B sweep". This is specific to sweeps — "a W&B run", "a W&B artifact", and "a W&B report" are current usage. | ||||||
| - **Generated content**, to fix upstream rather than here: the directories in README.md's [What files do I edit?](README.md#what-files-do-i-edit) table, `snippets/_includes/code-examples/` and `snippets/CodeSnippet.jsx` (synced from `wandb/docs-code-eval`), and any table wrapped in a `{/* takeru … automatically generated … */}` marker under `inference/` and `serverless-training/`. Pages in `weave/cookbooks/` are notebook-derived: each has a Jupyter notebook source at `weave/cookbooks/source/<page-name>.ipynb`. | ||||||
| - **ARIA chat examples**: When a task can be delegated to ARIA end-to-end in the W&B UI, add a compact chat example as a third content modality alongside code examples and UI click sequences. Use **ARIA** as the public-facing product name in prose and in fence titles. | ||||||
|
|
||||||
| Default format: a user prompt and a concise ARIA response. Don't include reasoning or thinking steps unless the page specifically needs them for clarity; longer walkthroughs belong on [ARIA overview](/aria/overview). Place chat examples in the first section where the ARIA-delegable task appears, not at the top of the page unless the whole page is about chatting with ARIA. | ||||||
|
|
||||||
|
|
@@ -113,7 +122,7 @@ To check or apply style, read the relevant pass file(s) and use them as guidance | |||||
|
|
||||||
| - **Regular reports only, not Fully Connected articles** — FC articles keep their full blog chrome in a frame and look broken. | ||||||
| - **Anonymous-viewable** — a public-project report or a [view-only link](/models/reports/cross-project-reports#view-only-report-links). The URL (with any `?accessToken=`) ships in public source and git history, so treat the report as public forever. | ||||||
| - **One or two per page**, skinny and purpose-built — each iframe boots the full W&B app at a fixed height, in its own light theme. | ||||||
| - **One or two per page**, skinny and purpose-built — each iframe boots the full W&B UI at a fixed height, in its own light theme. | ||||||
| - **English sources only** — not `ja/`, `ko/`, `fr/`. | ||||||
|
|
||||||
| A weekly CI job (`scripts/report-embeds/check_embeds.py`) verifies each embedded report still renders and files an issue if one breaks. It does not gate PRs. | ||||||
|
|
||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.