From 1b6227fce7048751fe687375dea4b9cee2cab734 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Mon, 13 Oct 2025 14:10:31 +0200 Subject: [PATCH 1/4] Update claude.md Signed-off-by: Iain Cox --- claude.md | 83 ++++++++++++++++++++++++++++++++++++++++++++++++++++--- 1 file changed, 79 insertions(+), 4 deletions(-) diff --git a/claude.md b/claude.md index c7341d0..cfe643e 100644 --- a/claude.md +++ b/claude.md @@ -8,7 +8,7 @@ ## Project context - Format: MDX files with YAML frontmatter - Config: docs.json for navigation, theme, settings -- Components: TigerData Cloud, TigerData console, TimescaleDB +- Components: Tiger, Tiger Console, TimescaleDB ## Content strategy - Document just enough for user success - not too much, not too little @@ -23,10 +23,35 @@ - Refer to the [docs.json schema](https://mintlify.com/docs.json) when building the docs.json file and site navigation ## Frontmatter requirements for pages -- title: Clear, descriptive page title -- description: Concise summary for SEO/navigation +- title: Clear, descriptive page title (meta title max 60 characters for SEO) +- description: Concise summary for SEO/navigation (under 200 characters) + +## Page structure requirements + +### Regular pages should include: +- Short intro paragraph that summarizes content in first sentence +- Visual illustration when helpful +- Descriptive headers using keywords +- Step-by-step procedures for actionable content +- Relevant internal and external links + +### API pages should include: +- Function name as title +- Brief description +- Usage samples with code blocks +- Arguments table with format: | Name | Type | Default | Required | Description | +- Returns section + +### Troubleshooting pages should include: +- Specific frontmatter fields (title, section, products/topics) +- Clear problem identification +- Step-by-step resolution procedures ## Writing standards +- Follow the Google Developer Documentation Style Guide with exceptions: + - Do not capitalize the first word after a colon + - Use code font (backticks) for UI elements instead of semi-bold +- Write clear, concise, and actionable documentation - Second-person voice ("you") - Prerequisites at start of procedural content - Test all code examples before publishing @@ -35,6 +60,26 @@ - Language tags on all code blocks - Alt text on all images - Relative paths for internal links +- If a product or concept is missing from the glossary, add it + +## Content reuse and formatting + +### Variables and links +- Use `{VARIABLE_NAME}` syntax for variables (reference snippets/vars.mdx for mappings) +- Internal links don't require full domain - use relative paths +- External links input as-is with full URLs + +### Supported formatting elements +- Tabs for organizing related content +- Code blocks with language tags +- Multi-tab code blocks for multiple language examples +- Tags for categorization + +### SEO optimization +- Use keywords in titles, headers, and intro paragraphs +- Summarize paragraph contents in first sentence +- Keep meta descriptions under 200 characters +- Keep meta titles under 60 characters ## Git workflow - NEVER use --no-verify when committing @@ -43,8 +88,38 @@ - Commit frequently throughout development - NEVER skip or disable pre-commit hooks +## Templates + +- For a new procedural page, use .github/templates/procedure.md as a template +- For a new integration page, use .github/templates/integration.md as a template + ## Do not - Skip frontmatter on any MDX file - Use absolute URLs for internal links - Include untested code examples -- Make assumptions - always ask for clarification \ No newline at end of file +- Make assumptions - always ask for clarification + +# Migration + +- Check the directory that the files are to move into +- Update all ${VARIABLES} to use the mintlify variables (reference snippets/vars.mdx for mappings) +- replace references to import since`` with `` Since `` on its own line after the frontmatter, followed by a newline before content begins +- replace references to import deprecated`` with `` Deprecated `` on its own line after the frontmatter, followed by a newline before content begins +- replace references to import DeprecationNotice with `` Deprecated on its own line after the frontmatter, followed by a newline before content begins +- replace references to import sunsetted`` with `` Sunsetted `` on its own line after the frontmatter, followed by a newline before content begins +- replace references to import EarlyAccess`` with `` Early access `` on its own line after the frontmatter, followed by a newline before content begins. if there is no version number, don't add one +- replace references to import Experimental with `` Early access on its own line after the frontmatter, followed by a newline before content begins. if there is no version number, don't add one +- Ask where the other imported files should go in the snippets directory (initially manual, but track patterns to automate over time) +- Update the metadata in each file, rename the excerpt metadata name as description, and api_name as title +- Remove api: and version: metadata sections, indent license and type under root level +- Put the value of stable in a since icon (e.gple., if stable: 1.0.0, add Since 1.0.0 icon), then remove the stable metadata item +- Remove the first # header from the content (title is handled by frontmatter) +- Replace `` blocks with `` blocks (with newlines between tags and text) +- Change ### Required arguments to ## Arguments with new table format: | Name | Type | Default | Required | Description | +- Required arguments get ✔ in Required column, - in Default column (unless default specified) +- Merge Optional arguments section into the same table with ✔ in Required column for optional args +- Change ### Samples to ## Samples +- Change **Returns:** to ## Returns with newline before text +- Update internal links to use the correct Mintlify repository structure +- Check all content so it will render correctly in Mintlify +- Update the docs.json to include the files in the structure. The docs.json structure reflects the folder structure - initially ask for placement, but learn patterns over time From 64a28aaf2bd3e791a2dd8c9f0f291ee902a4f278 Mon Sep 17 00:00:00 2001 From: Iain Cox Date: Mon, 3 Nov 2025 11:16:05 +0000 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Anastasiia Tovpeko <114177030+atovpeko@users.noreply.github.com> Signed-off-by: Iain Cox --- claude.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/claude.md b/claude.md index cfe643e..462d608 100644 --- a/claude.md +++ b/claude.md @@ -24,7 +24,7 @@ ## Frontmatter requirements for pages - title: Clear, descriptive page title (meta title max 60 characters for SEO) -- description: Concise summary for SEO/navigation (under 200 characters) +- description: Concise summary for SEO/navigation/search (under 200 characters) ## Page structure requirements From 8ed9a3aad02d8d4228a154efdf37bcb4c1f91a34 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 3 Nov 2025 11:16:40 +0000 Subject: [PATCH 3/4] chore: updates on review. --- claude.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/claude.md b/claude.md index 462d608..2fe62fd 100644 --- a/claude.md +++ b/claude.md @@ -1,4 +1,4 @@ -# TigerData documentation +# Tiger Data documentation ## Working relationship - You can push back on ideas-this can lead to better documentation. Cite sources and explain your reasoning when you do so @@ -8,7 +8,7 @@ ## Project context - Format: MDX files with YAML frontmatter - Config: docs.json for navigation, theme, settings -- Components: Tiger, Tiger Console, TimescaleDB +- Components: Tiger Cloud, Tiger Console, TimescaleDB, Agentic Postgres ## Content strategy - Document just enough for user success - not too much, not too little @@ -50,7 +50,7 @@ ## Writing standards - Follow the Google Developer Documentation Style Guide with exceptions: - Do not capitalize the first word after a colon - - Use code font (backticks) for UI elements instead of semi-bold + - Use semi-bold for UI elements - Write clear, concise, and actionable documentation - Second-person voice ("you") - Prerequisites at start of procedural content @@ -69,7 +69,7 @@ - Internal links don't require full domain - use relative paths - External links input as-is with full URLs -### Supported formatting elements +### Supported formatting - Tabs for organizing related content - Code blocks with language tags - Multi-tab code blocks for multiple language examples From 704b6b6037d94b98a7e94d7b452436f37a797cf1 Mon Sep 17 00:00:00 2001 From: billy-the-fish Date: Mon, 3 Nov 2025 13:32:52 +0000 Subject: [PATCH 4/4] chore: I know this is the wrong PG, but just to do a quick logo update. --- docs.json | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs.json b/docs.json index 620aa1d..7515571 100644 --- a/docs.json +++ b/docs.json @@ -537,8 +537,8 @@ "family": "Geist" }, "logo": { - "light": "https://assets.timescale.com/timescale-web/shared/logo/tigerdata-logo-black.svg", - "dark": "https://assets.timescale.com/timescale-web/shared/logo/tigerdata-logo-white.svg" + "light": "https://assets.timescale.com/timescale-web/brand/show/horizontal-black.svg", + "dark": "https://assets.timescale.com/timescale-web/brand/show/horizontal-white.svg" }, "navbar": { "links": [