[docs] platform core concept revamp and overview update (#3664)
This commit is contained in:
Parth Sharma
+1
@@ -14,6 +14,7 @@ API reference pages document a single endpoint contract. Present metadata, reque
|
||||
- Frontmatter must include `title`, `description`, `icon`, `method`, `path`. Heading should be `# METHOD /path`.
|
||||
- Provide a quick facts table (Method, Path, Auth, Rate limit) followed by an `<Info>` block describing when to use the endpoint. Add `<Warning>` for beta headers or scope requirements.
|
||||
- Requests require headers table, body/parameters table, and `<CodeGroup>` with cURL, Python, TypeScript. If a language is unavailable, include a `<Note>` explaining why.
|
||||
- When migrating an existing endpoint page, keep the canonical examples and edge-case notes—drop them into these sections rather than inventing new payloads unless the API changed.
|
||||
- Response section must show a canonical success payload, status-code table, and troubleshooting tips. Document pagination/idempotency in `<Tip>` or `<Note>` blocks.
|
||||
- End with related endpoints, a sample workflow link, and two CTA cards (left = concept/feature, right = applied tutorial). Keep the comment reminder for reviewers.
|
||||
|
||||
|
||||
+1
@@ -14,6 +14,7 @@ Concept guides establish a shared mental model before feature or API docs. Defin
|
||||
- Frontmatter must include `title`, `description`, `icon`. Lead with a definition + analogy in two sentences max.
|
||||
- Add an `<Info>` block (“Why it matters”) with 2–3 bullets summarizing user impact. Use `<Warning>` near limitations or beta callouts.
|
||||
- Introduce vocabulary via `## Key terms` (table or bullets) before diving deeper.
|
||||
- When migrating legacy pages, preserve canonical distinctions (e.g., short-term vs long-term) and fold them into the template rather than replacing them with new frameworks.
|
||||
- Organize the body with question-style headings (`How does it work?`, `When should you use it?`, `How it compares`). Optional diagrams should be left-to-right (`graph LR`).
|
||||
- Include at least one light code/JSON snippet or data table so the concept ties back to implementation.
|
||||
- Close with a “Put it into practice” checklist, “See it live” links, and the standard two-card CTA (left = feature/reference, right = applied cookbook).
|
||||
|
||||
Vendored
+1
@@ -15,6 +15,7 @@ Cookbooks are narrative tutorials. They start with a real problem, show the brok
|
||||
- Keep tone conversational; use real names ("Max", "Sarah"), not `user_123`.
|
||||
- Opening must stay tight: ≤2 short paragraphs (no bullet lists) before the first section.
|
||||
- Inline expected outputs immediately after each code block.
|
||||
- When modernizing an existing cookbook, keep the narrative beats, screenshots, and sample outputs—reshape them into this arc instead of rewriting unless the workflow changed.
|
||||
- Limit callouts to 3–5 per page. Prefer narrative text over stacked boxes.
|
||||
- Always provide Python **and** TypeScript tabs when an SDK exists for both.
|
||||
- Every page must end with exactly two navigation cards (left = related/side quest, right = next cookbook in the journey).
|
||||
|
||||
+1
@@ -19,6 +19,7 @@ Use this when you introduce or deepen a single Mem0 capability (Graph Memory, Ad
|
||||
- Frontmatter stays outcome-driven: `title`, `description`, `icon`, optional `badge` (e.g., “Advanced”).
|
||||
- Opening paragraph = two sentences: problem, then payoff. Keep energy high right from the start.
|
||||
- Include an `<Info>` block titled “You’ll use this when…” with 3 bullets (user persona, workload, expected benefit).
|
||||
- When reshaping legacy feature docs, carry over existing diagrams, tables, and gotchas—organize them under these headings rather than replacing them unless the product has changed.
|
||||
- If there’s a known caveat (pricing, performance), surface it early in a `<Warning>` so readers don’t get surprised later.
|
||||
- Optional but encouraged: add a Mermaid diagram right after the intro to show how components connect; delete it if the story is obvious without visuals.
|
||||
- Add a `## Configure access` snippet (even if it’s “Confirm your Mem0 API key is already configured”) so contributors never forget to mention the baseline setup.
|
||||
|
||||
@@ -14,6 +14,7 @@ Integration guides prove a joint journey: configure Mem0 and the partner with mi
|
||||
- Frontmatter must include `title`, `description`, `icon`, and optional `partnerBadge`/`tags`. State the joint value in one sentence right after the H1.
|
||||
- List prerequisites for **both** platforms inside an `<Info>` block. Surface limited-access or beta flags in a `<Warning>` before any setup.
|
||||
- Default to Tabs + Steps when instructions diverge (Platform vs OSS, Python vs TypeScript). When only one path exists, add a `<Note>` explaining the missing variant.
|
||||
- When migrating an existing integration, keep the proven steps/screenshots—map them into this structure rather than rewriting unless either product has changed.
|
||||
- Keep any Mermaid diagrams optional and left-to-right (`graph LR`) to avoid vertical overflow; use only if architecture clarity is needed.
|
||||
- Every major step must finish with a verification `<Info icon="check">`. End the page with exactly two CTA cards (left = related reference, right = next integration/cookbook).
|
||||
|
||||
|
||||
+1
@@ -14,6 +14,7 @@ Migrations lower blood pressure. They explain what’s changing, why it matters,
|
||||
- Keep the frontmatter complete (`title`, `description`, `icon`, `versionFrom`, `versionTo`, and optional `releaseDate`). Readers should know at a glance what versions they are moving between.
|
||||
- Start with context: summary table + “Should you upgrade?” checklist. Highlight deadlines with `<Warning>` and call out optional paths with `<Tip>`.
|
||||
- Break the body into **Plan → Migrate → Validate**. Use numbered headings inside **Migrate** and put rollback instructions directly after any risky step.
|
||||
- When porting older migration guides, keep existing change tables, screenshots, and warnings—slot them into this format unless the upgrade path has materially changed.
|
||||
- Document breaking changes with an `Old behavior` vs `New behavior` table. Use `<Info icon="check">` for mandatory verification steps.
|
||||
- Optional flow diagrams are allowed, but only when a left-to-right Mermaid (`graph LR`) clarifies the upgrade path.
|
||||
- End with two CTA cards (left = deep dive reference, right = applied example) and keep the comment reminder for reviewers.
|
||||
|
||||
+1
@@ -15,6 +15,7 @@ Operation guides focus on a single action (add, search, update, delete). Show th
|
||||
- Lead with a two-sentence promise (problem → outcome), followed by an `<Info>` prerequisites block and optional `<Warning>` for hazards (overwrites, rate limits).
|
||||
- Include a “When to pick this” bullet list (≤3 items) so readers confirm they’re in the right doc.
|
||||
- Use Tabs with Python and TypeScript examples. If only one SDK exists, add a `<Note>` stating that explicitly.
|
||||
- When migrating legacy guides, keep existing code paths and notes—slot them into these sections instead of replacing them unless behavior changed.
|
||||
- Provide `<Info icon="check">` verification after each critical step; call out the most common error with a `<Warning>` close to where it can occur.
|
||||
- End with exactly two CTA cards: left = conceptual depth, right = applied example/cookbook.
|
||||
|
||||
|
||||
@@ -14,6 +14,7 @@ Parameter references document every input/output detail for one operation after
|
||||
- Frontmatter requires `title`, `description`, `icon`. Titles should mirror the operation (“Add Memories Parameters”).
|
||||
- Place canonical Python and TypeScript signatures right under the heading using `<CodeGroup>`. Mention defaults or breaking changes in an `<Info>` or `<Warning>` immediately after.
|
||||
- Parameter table must include columns: Name, Type, Required, Description, Notes. Add a Managed/OSS distinction either as a column or in Notes.
|
||||
- When updating legacy parameter sheets, keep the authoritative field lists and notes—reformat them into this structure rather than trimming details unless the schema changed.
|
||||
- Response table must include Field, Type, Description, Example. For nested objects, add subtables or `<CodeGroup>` JSON snippets beneath the row.
|
||||
- Examples section should show minimal Python and TypeScript calls with one-sentence explanations. If a language is missing, include a `<Note>` explaining why.
|
||||
- Finish with related operations, troubleshooting tied to parameter misuse, and a two-card CTA (operation guide on the left, cookbook/integration on the right).
|
||||
|
||||
+1
@@ -14,6 +14,7 @@ Quickstarts are the fastest path to first success. Each page should configure th
|
||||
- Keep the intro tight: one-sentence promise + `<Info>` prerequisites. Add `<Warning>` only for blocking requirements (e.g., “requires paid tier”).
|
||||
- Default to Python + TypeScript examples inside `<Tabs>` with `<Steps>` per language. If a second language truly doesn’t exist, add a `<Note>` explaining why.
|
||||
- Every journey must follow **Install → Configure → Add → Search → Delete** (or closest equivalents). Drop verification `<Info icon="check">` immediately after the critical operation.
|
||||
- When migrating an existing quickstart, reuse canonical snippets and screenshots—reshape them into this flow rather than rewriting content unless the product changed.
|
||||
- If you include a Mermaid diagram, keep it optional and render left-to-right (`graph LR`) so it doesn’t flood the page.
|
||||
- End with exactly two CTA cards: left = related/alternative path, right = next step in the journey. No link farms.
|
||||
|
||||
|
||||
+1
@@ -14,6 +14,7 @@ Release notes are heartbeat updates. They tell readers what shipped, what needs
|
||||
- Frontmatter must include `title`, `description`, `icon`, `releaseDate`, and `version`. Add `tags` if you need filters (e.g., `["platform", "oss"]`).
|
||||
- Lead with a one-sentence headline plus a quick stats table (New features, Fixes, Required action). Keep the TL;DR in an `<Info>` block; use `<Warning>` only for breaking changes or deadlines.
|
||||
- Organize the body into Highlights, Improvements & fixes (grouped by product), and Known issues. Each bullet links to docs where appropriate.
|
||||
- When reshaping older release notes, retain the shipped items and shout-outs—map them to these sections instead of rewriting history.
|
||||
- Include an Upgrade checklist with concrete next steps. Optional “Community shout-outs” should remain short.
|
||||
- Two-card CTA at the end, as always: left = deeper reference, right = applied next step.
|
||||
|
||||
|
||||
+30
-16
@@ -13,7 +13,9 @@ Overview pages orient readers for an entire section. Summarize who it’s for, s
|
||||
## ❌ DO NOT COPY — Guidance & Constraints
|
||||
- Frontmatter must include `title`, `description`, `icon`. Keep the hero paragraph under two sentences describing audience + outcome.
|
||||
- Provide an `<Info>` block pointing to the primary entry point (usually the quickstart). Use `<Warning>` only for major caveats (beta, deprecation).
|
||||
- Card grids should list 4–6 journeys max using `<CardGroup cols={3}>` or `<Cards>`. Copy must stay ≤15 words, and every card needs an icon + link.
|
||||
- Stage journeys in 4–6 cards total. Break into multiple `<CardGroup>` rows when a binary choice (e.g., Python vs Node) or stacked journeys reads better. Keep copy ≤15 words with icons + links.
|
||||
- When migrating an existing overview, reuse the established journeys, images, and stats—reshape them into this layout rather than cutting content unless it’s outdated.
|
||||
- Optional accordions (`<AccordionGroup>`) can tuck detailed tables (feature breakdowns, comparisons) beneath the hero when extra context is helpful.
|
||||
- Optional visuals (comparison table, Mermaid diagram) should be left-to-right and only added when they reduce confusion.
|
||||
- Finish with exactly two CTA cards: left = adjacent/alternative track, right = next logical step deeper in the section.
|
||||
|
||||
@@ -36,6 +38,15 @@ icon: "compass"
|
||||
Start with [Quickstart link] if you’re new, then choose a deeper topic below.
|
||||
</Info>
|
||||
|
||||
{/* Optional: delete if not needed */}
|
||||
<AccordionGroup>
|
||||
<Accordion title="[Optional value table]" icon="sparkles">
|
||||
| Feature | Why it helps |
|
||||
| --- | --- |
|
||||
| ... | ... |
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
{/* Optional: delete if not needed */}
|
||||
```mermaid
|
||||
graph LR
|
||||
@@ -46,27 +57,30 @@ graph LR
|
||||
|
||||
## Choose your path
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="[Journey 1]" icon="rocket" href="/[link-1]">
|
||||
{/* Use multiple rows if a 2-up decision helps */}
|
||||
<CardGroup cols={2}>
|
||||
<Card title="[Decision 1]" icon="rocket" href="/[link-1]">
|
||||
[One-line outcome]
|
||||
</Card>
|
||||
<Card title="[Journey 2]" icon="brain" href="/[link-2]">
|
||||
[One-line outcome]
|
||||
</Card>
|
||||
<Card title="[Journey 3]" icon="sparkles" href="/[link-3]">
|
||||
[One-line outcome]
|
||||
</Card>
|
||||
<Card title="[Journey 4]" icon="book" href="/[link-4]">
|
||||
[One-line outcome]
|
||||
</Card>
|
||||
<Card title="[Journey 5]" icon="life-ring" href="/[link-5]">
|
||||
[One-line outcome]
|
||||
</Card>
|
||||
<Card title="[Journey 6]" icon="gear" href="/[link-6]">
|
||||
<Card title="[Decision 2]" icon="brain" href="/[link-2]">
|
||||
[One-line outcome]
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="[Journey 1]" icon="sparkles" href="/[link-3]">
|
||||
[One-line outcome]
|
||||
</Card>
|
||||
<Card title="[Journey 2]" icon="gear" href="/[link-4]">
|
||||
[One-line outcome]
|
||||
</Card>
|
||||
<Card title="[Journey 3]" icon="book" href="/[link-5]">
|
||||
[One-line outcome]
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
{/* Duplicate another CardGroup (2 or 3 columns) if you need more coverage, but keep the total ≤6 cards. */}
|
||||
|
||||
<Tip>
|
||||
[Optional cross-link, e.g., “Self-hosting? Jump to the OSS overview.”] Delete if unused.
|
||||
</Tip>
|
||||
|
||||
@@ -14,6 +14,7 @@ Troubleshooting playbooks map symptoms to diagnostics and fixes. Keep them fast
|
||||
- Frontmatter must include `title`, `description`, `icon`. Lead with one sentence about the system or workflow this playbook covers.
|
||||
- Add an `<Info>` block (“Use this when…”) and a quick index table (Symptom, Likely cause, Fix link). Surface critical safety warnings in `<Warning>`.
|
||||
- Each symptom section needs: diagnostic command/snippet, `<Info icon="check">` expected output, `<Warning>` for the observed failure, numbered fix steps, and optional `<Tip>` for prevention.
|
||||
- If you’re migrating an existing playbook, carry forward the known failure modes and scripts—reformat them into this structure unless the troubleshooting path changed.
|
||||
- Group unrelated issues with horizontal rules and provide escalation guidance when self-service stops.
|
||||
- Conclude with prevention checklist, related docs, and the standard two-card CTA (concept/reference left, applied workflow right).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user