|
| 1 | +# Firestore JavaScript SDK Developer Documentation |
| 2 | + |
| 3 | +This folder contains the developer documentation for the Firestore JavaScript SDK. |
| 4 | + |
| 5 | +**Audience:** |
| 6 | +1. **Maintainers**: Engineers working on the SDK internals. |
| 7 | +2. **AI Agents**: Automated assistants reading this consistency to understand the codebase. |
| 8 | + |
| 9 | +**NOT Audience:** |
| 10 | +- 3rd Party Developers (App Developers). They should use the [official Firebase documentation](https://firebase.google.com/docs/firestore). |
| 11 | + |
| 12 | +# Entry Point |
| 13 | +Start at [./overview.md](./overview.md). |
| 14 | + |
| 15 | +# Content Guidelines |
| 16 | + |
| 17 | +## Principles |
| 18 | +- **High-Level Focus**: Explain architecture and data flow. Avoid duplicating code. |
| 19 | +- **Why > How**: Explain *why* a design choice was made. The code shows *how*. |
| 20 | +- **Reference by Name**: Use exact component/interface names (e.g., `Persistence`, `EventManager`). |
| 21 | + |
| 22 | +## Terminology |
| 23 | +- **Concepts First**: **Aggressively favor** high-level English concepts over code identifiers. Only drop down to code identifiers when absolutely necessary for precise mapping. |
| 24 | + * *Good*: "The Mutation Queue stores pending writes." |
| 25 | + * *Bad*: "The `mutationQueues` store contains `DbMutationBatch` objects." |
| 26 | + * *Acceptable (Mapping)*: "The Mutation Queue (implemented as `mutationQueues` store)..." |
| 27 | +- **Avoid Over-Specification**: Do not generally reference private/internal variable names unless documenting that specific module's internals. |
| 28 | +- **Strict Casing**: When you *must* reference code, use the **exact casing** found in the codebase (e.g., `mutationQueues`). |
| 29 | +- **No "Translations"**: Never convert code names into snake_case. Either use the English Concept ("Remote Documents") or the exact Code Name (`remoteDocuments`). |
| 30 | + |
| 31 | +## Diagramming |
| 32 | +Use **Mermaid** for diagrams. |
| 33 | +- Flowcharts for logic. |
| 34 | +- Sequence diagrams for async protocols. |
| 35 | +- Class diagrams for component relationships. |
| 36 | + |
| 37 | +# Style Guide |
| 38 | +- **Syntax**: Markdown (GFM). |
| 39 | +- **Voice**: Active voice ("The SDK does X"). |
| 40 | +- **Tense**: Present tense ("The query executes..."). |
| 41 | +- **Mood**: Imperative for instructions ("Run the build..."). |
| 42 | +- **Conciseness**: Short sentences. Bullet points where possible. |
| 43 | + |
| 44 | +# Maintenance |
| 45 | +- **Co-location**: Keep documentation close to the code it describes (linked via `Code Layout`). |
| 46 | +- **Atomic Updates**: Update documentation in the *same PR* as the feature or fix. |
| 47 | +- **Freshness**: If you see stale docs, fix them immediately. |
0 commit comments