From d6fadde50d3ea25f180b5d3226d19e7545238244 Mon Sep 17 00:00:00 2001 From: Alexander Date: Wed, 13 May 2026 12:39:16 +0200 Subject: [PATCH] Track BlueDoc and GreenDoc document templates --- docs/templates/bluedoc.md | 96 ++++++++++++++++++++++++++++++++++++++ docs/templates/greendoc.md | 56 ++++++++++++++++++++++ 2 files changed, 152 insertions(+) create mode 100644 docs/templates/bluedoc.md create mode 100644 docs/templates/greendoc.md diff --git a/docs/templates/bluedoc.md b/docs/templates/bluedoc.md new file mode 100644 index 0000000..c380ee1 --- /dev/null +++ b/docs/templates/bluedoc.md @@ -0,0 +1,96 @@ +# [Project Name]: Design Doc + +**Authors:** [Author Name(s)] +**Status:** [Draft / In-Review / Approved / Obsolete] +**Last Updated:** YYYY-MM-DD +**Reviewers:** [List of reviewers, usually @usernames] +**Approvers:** [List of final decision makers] +**Document Link:** [Link to this file or rendered version] + +--- + +## 1. Abstract +A high-level summary (1–3 paragraphs) of what the project is, what problem it solves, and the proposed solution. This should be readable by a non-expert. + +## 2. Background +Context for why this project exists. +- What is the current state? +- What are the pain points? +- Are there existing systems that this will replace or interact with? +- Include links to relevant PRDs (Product Requirement Documents) or previous design docs. + +## 3. Goals & Non-Goals +Clarity on scope is critical to prevent scope creep. + +### 3.1. Goals +* **Primary Goal:** The most important outcome. +* Metric-driven goals (e.g., "Reduce latency by 20%"). +* Functional requirements (e.g., "Allow users to edit comments"). + +### 3.2. Non-Goals +* Features that might seem related but are explicitly out of scope. +* Future improvements that are deferred. + +## 4. Proposed Design +The "meat" of the document. Start with the high-level architecture and zoom in. + +### 4.1. High-Level Architecture +Provide a high-level diagram or description of how the system fits together. +> *Tip: Use Mermaid.js or link to an embedded image.* + +### 4.2. Detailed Design +Go into specific components, APIs, and data models. +* **API Definitions:** Describe new endpoints, Protobuf definitions, or CLI commands. +* **Data Schema:** Database tables, key-value structures, or file formats. +* **Workflows:** Step-by-step logic for complex operations (e.g., auth flow). + +## 5. Cross-Cutting Concerns +Google design docs place heavy emphasis on these "standard" reviews. + +### 5.1. Security & Privacy +- How is data encrypted? +- What are the access control lists (ACLs)? +- Does this handle PII (Personally Identifiable Information)? + +### 5.2. Observability (Monitoring & Logging) +- What metrics will be exported (e.g., RPC error rates, latency)? +- What logging is required for debugging? +- What are the "Golden Signals" for the dashboard? + +### 5.3. Scalability & Performance +- What are the expected QPS (Queries Per Second)? +- How does the system scale (Horizontal vs. Vertical)? +- What are the resource requirements (CPU, RAM, Storage)? + +### 5.4. Testing Plan +- Unit tests, integration tests, and end-to-end tests. +- Strategy for load testing or "chaos" testing. + +## 6. Alternatives Considered +*A BlueDoc is not just about the chosen path, but why others were rejected.* +* **Alternative A:** Briefly describe it and why it was rejected (e.g., "Too complex," "High latency"). +* **Alternative B:** Why "Doing Nothing" is not an option. + +## 7. Implementation Plan +- **Phase 1:** Minimum Viable Product (MVP). +- **Phase 2:** Feature parity or migrations. +- **Rollout/Rollback:** How will the feature be toggled? (e.g., feature flags). + +## 8. Glossary / References +- Links to external libraries. +- Definitions for project-specific acronyms. + +--- + +### Markdown Style Tips (Google Conventions): +1. **Line Length:** Google's internal style guide suggests a soft limit of **80 characters** per line for source Markdown to make it easier to review in code-diff tools. +2. **Headings:** Use `#` for title, `##` for sections, and `###` for subsections. +3. **TOC:** If your environment supports it, use `[TOC]` at the top to generate a Table of Contents. +4. **Diagrams:** Use **Mermaid** blocks if using GitHub/GitLab, otherwise link to a stable SVG/PNG. + ```mermaid + graph TD; + A-->B; + A-->C; + B-->D; + C-->D; + ``` diff --git a/docs/templates/greendoc.md b/docs/templates/greendoc.md new file mode 100644 index 0000000..0011a0c --- /dev/null +++ b/docs/templates/greendoc.md @@ -0,0 +1,56 @@ +# [Project Name]: Design One-Pager (GreenDoc) + +**Author(s):** [Name] +**Status:** [Draft / Approved / Shipped] +**Last Updated:** YYYY-MM-DD +**Estimated Effort:** [e.g., 2 weeks, 1 sprint] + +--- + +## 1. Summary +A 2–3 sentence overview of the change. What are you doing and why? + +## 2. Problem Statement +Describe the specific pain point or "broken" state this project addresses. +* *Example: Currently, users cannot filter their search history by date, leading to high latency in manual lookup.* + +## 3. Proposed Solution +Explain the high-level logic of the fix or feature. +* What is the specific code change or configuration update? +* How does it interact with existing systems? +* *Note: Use a single simple diagram if the logic is non-trivial.* + +## 4. Risks & Trade-offs +Even small changes have risks. Address them upfront. +* **Performance:** Will this increase memory usage? +* **Complexity:** Does this add a new dependency? +* **Backwards Compatibility:** Will this break existing clients? +* **Alternatives:** Why did you choose this over a "quicker" or "better" fix? + +## 5. Success Criteria (Metrics) +How will you know this worked? +* [ ] Primary metric (e.g., "Feature usage > 5%") +* [ ] Guardrail metric (e.g., "Latency does not increase by > 10ms") + +## 6. Implementation & Rollout +A brief bulleted list of the steps to ship. +1. Feature flag implementation. +2. Canary to 1% of users. +3. Full rollout. + +--- + +### Comparison: BlueDoc vs. GreenDoc + +| Feature | BlueDoc (Standard) | GreenDoc (One-Pager) | +| :--- | :--- | :--- | +| **Scope** | Major systems, new services. | Small features, optimizations, bug fixes. | +| **Length** | 5–20+ pages. | 1–2 pages. | +| **Review** | Cross-functional committees (SRE, Security). | Peer-level or Team Lead review. | +| **Focus** | Long-term scalability and architecture. | Immediate impact and implementation. | + +### Markdown Tips for GreenDocs: +* **Be Brutally Concise:** If a section requires more than three paragraphs, consider upgrading to a **BlueDoc**. +* **Checklists:** Use `[ ]` to show remaining work or requirements. +* **Inline Links:** Link directly to the relevant code files or bug tracker (Jira/Buganizer) to keep the doc self-contained. +