Skip to content

Commit a98cbc3

Browse files
MGibson1MGibson1
committed
wrap filename references in ``
1 parent 27e3a22 commit a98cbc3

2 files changed

Lines changed: 19 additions & 19 deletions

File tree

‎docs/contributing/documentation/diagrams.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -105,7 +105,7 @@ C4 is adopted as a **mental model only**. We are explicitly **NOT** adopting any
105105

106106
## Ownership and currency (rules 7 and 8)
107107

108-
- The owner is CODEOWNERS for in-repo docs and the page's owning team on Confluence.
108+
- The owner is `CODEOWNERS` for in-repo docs and the page's owning team on Confluence.
109109
- Updates land in the same PR or page edit as the change the diagram depicts. A diagram known to be
110110
wrong is deleted or updated rather than left to mislead.
111111
- Every repo's root `CLAUDE.md` MUST carry the base documentation obligations, which cover diagrams:

‎docs/contributing/documentation/index.md‎

Lines changed: 18 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -57,8 +57,8 @@ typically its `README.md`, and splits into a `docs/` folder beside it when it ou
5757
[Component documentation](./component-documentation.md). Wherever this standard says `README.md` or
5858
`docs/`, it means that artifact at either stage.
5959

60-
AI instruction files (CLAUDE.md, rules, skills) are not documentation: they are instructions on how
61-
to behave and how to consume documentation. This standard does not govern them, and content that
60+
AI instruction files (`CLAUDE.md`, rules, skills) are not documentation: they are instructions on
61+
how to behave and how to consume documentation. This standard does not govern them, and content that
6262
belongs in documentation MUST NOT live in an instruction file, since that would give it a second
6363
home.
6464

@@ -76,7 +76,7 @@ Apply in order. First match wins:
7676
for tech breakdowns and work specifications, **Confluence** in the owning team's space for
7777
everything else.
7878
2. Does it describe **code in one repo**? → **that repo**, in the owning scope's
79-
[README.md or docs/](./component-documentation.md).
79+
[`README.md` or `docs/`](./component-documentation.md).
8080
3. Is it **how to contribute or build**, **architecture spanning repos**, or an **architectural
8181
decision**? → **contributing.bitwarden.com**
8282
([bitwarden/contributing-docs](https://github.com/bitwarden/contributing-docs)), behind the
@@ -127,19 +127,19 @@ propose the fix and the new row in the same PR.
127127

128128
#### In the repo
129129

130-
| Documentation type | Home | Format |
131-
| ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------- | -------------------------------------------------- |
132-
| Component docs: what one library, crate, or feature does and how to use it | `README.md` (or the component's `docs/`) next to the code | [Component documentation][component-docs] |
133-
| Guides spanning multiple components in one repo | `docs/` or README at the components' lowest common ancestor | [Component documentation][component-docs] |
134-
| Architecture of one repo | The owning scope's `docs/` or README | [Component documentation][component-docs] |
135-
| Repo overview, build entry point | Root `README.md` | The [bitwarden/template][template] README skeleton |
136-
| New-repo doc scaffolding (README skeleton, CONTRIBUTING pointer, `.claude/`) | [bitwarden/template][template] | — |
137-
| Repo-specific code style overrides (coupled to lint/formatter config) | Repo `docs/`, linking the org baseline | — |
138-
| API / SDK reference | Doc comments in source | [Component documentation][component-docs] |
139-
| UI component library usage docs (audience: developers **and** designers) | `.mdx` colocated with the UI component, rendered at [components.bitwarden.com][storybook] | Storybook `autodocs` |
140-
| Changelog for a published artifact | `CHANGELOG.md` next to the artifact | Ecosystem convention |
141-
| Platform-mandated files (`SECURITY.md`, `.github` templates, CODEOWNERS, registry READMEs, store metadata) | Path fixed by the platform | Platform-defined |
142-
| Legal, licensing, and trademark notices | Repo root | — |
130+
| Documentation type | Home | Format |
131+
| ------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------- | -------------------------------------------------- |
132+
| Component docs: what one library, crate, or feature does and how to use it | `README.md` (or the component's `docs/`) next to the code | [Component documentation][component-docs] |
133+
| Guides spanning multiple components in one repo | `docs/` or README at the components' lowest common ancestor | [Component documentation][component-docs] |
134+
| Architecture of one repo | The owning scope's `docs/` or README | [Component documentation][component-docs] |
135+
| Repo overview, build entry point | Root `README.md` | The [bitwarden/template][template] README skeleton |
136+
| New-repo doc scaffolding (README skeleton, CONTRIBUTING pointer, `.claude/`) | [bitwarden/template][template] | — |
137+
| Repo-specific code style overrides (coupled to lint/formatter config) | Repo `docs/`, linking the org baseline | — |
138+
| API / SDK reference | Doc comments in source | [Component documentation][component-docs] |
139+
| UI component library usage docs (audience: developers **and** designers) | `.mdx` colocated with the UI component, rendered at [components.bitwarden.com][storybook] | Storybook `autodocs` |
140+
| Changelog for a published artifact | `CHANGELOG.md` next to the artifact | Ecosystem convention |
141+
| Platform-mandated files (`SECURITY.md`, `.github` templates, `CODEOWNERS`, registry READMEs, store metadata) | Path fixed by the platform | Platform-defined |
142+
| Legal, licensing, and trademark notices | Repo root | — |
143143

144144
#### On contributing.bitwarden.com
145145

@@ -210,7 +210,7 @@ even when correction is not prioritized.
210210

211211
### Owners
212212

213-
Ownership follows CODEOWNERS for in-repo docs. Confluence pages name an owning team in the header
213+
Ownership follows `CODEOWNERS` for in-repo docs. Confluence pages name an owning team in the header
214214
and SHOULD follow the owners of the Confluence space.
215215

216216
Owners are responsible for the maintenance and general health of the documentation they own.
@@ -273,6 +273,6 @@ formality, since readers and tooling act on their exact wording:
273273
A documentation change (or the doc portion of a code change) is done when it satisfies
274274
[the standard](#the-standard) and the [style guide](#style-guide-rule-5).
275275

276-
For a **code** change, every README, `docs/` page, diagram, doc comment, and CLAUDE.md that
276+
For a **code** change, every README, `docs/` page, diagram, doc comment, and `CLAUDE.md` that
277277
describes the changed behavior MUST be updated in the same PR. If none described it but it warrants
278278
documentation per the [component README standard](./component-documentation.md), add it.

0 commit comments

Comments
 (0)