Conversation
Remove the ranty intro paragraph and tighten each bullet to one or two sentences. Keep the same points, lose the sermon. https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
PR ReviewThis is a docs-only change trimming the Why section of the README. The edit achieves its stated goal: the new copy is more direct and less preachy. What works well:
Minor observations:
No issues with correctness or accuracy — all factual claims carry over correctly. Overall: good cleanup, ready to merge with or without the minor suggestions above. |
There was a problem hiding this comment.
Pull request overview
This PR refines the “Why Tinkerdown?” section of the README to be shorter and less ranty, aiming for concise positioning of Tinkerdown’s single-file, markdown/YAML-driven approach for internal tools.
Changes:
- Replaced the long introductory paragraph with a short, direct framing statement.
- Rewrote the “Why” bullets to be 1–2 sentences each.
- Simplified several bullet claims and examples for brevity.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
README.md
Outdated
| Most internal tools don't need a framework. Tinkerdown replaces the scaffolding with a single markdown file — data sources in YAML, layout in markdown, interactions via HTML attributes. | ||
|
|
||
| - **One file = one app.** Data connections, layout, and interactions all live in one place. No build step, no dependencies, no boilerplate. | ||
| - **AI gets it right.** The format is small and declarative enough that LLMs produce working apps consistently — no component trees or state management to misconfigure. |
There was a problem hiding this comment.
“LLMs produce working apps consistently” reads as a marketing claim and isn’t easily verifiable. To keep this section factual, consider describing the concrete property (small, constrained, declarative format) and the expected benefit (easier for AI to generate/edit) without asserting consistent success.
README.md
Outdated
| - **Made for disposable software.** The admin panel for this sprint. The tracker for that hiring round. The runbook for on-call week. Software you'd never justify scaffolding a React project for, but that's genuinely useful for a few days or weeks. When you're done, the markdown is still readable on its own. | ||
| Most internal tools don't need a framework. Tinkerdown replaces the scaffolding with a single markdown file — data sources in YAML, layout in markdown, interactions via HTML attributes. | ||
|
|
||
| - **One file = one app.** Data connections, layout, and interactions all live in one place. No build step, no dependencies, no boilerplate. |
There was a problem hiding this comment.
“No dependencies” is ambiguous and may be read as “nothing to install besides the markdown file,” even though you still need the Tinkerdown binary and potentially DB drivers/access. Consider tightening this to a precise claim like “no build step” / “no npm/node_modules” to avoid overstating.
| - **One file = one app.** Data connections, layout, and interactions all live in one place. No build step, no dependencies, no boilerplate. | |
| - **One file = one app.** Data connections, layout, and interactions all live in one place. No build step, no npm/node_modules, no boilerplate. |
README.md
Outdated
| - **AI gets it right.** The format is small and declarative enough that LLMs produce working apps consistently — no component trees or state management to misconfigure. | ||
| - **8 data sources out of the box.** SQLite, PostgreSQL, REST APIs, JSON, CSV, shell commands, markdown, and WASM. Point at existing infrastructure and get a working UI. | ||
| - **Start simple, add power as needed.** Plain markdown tables become editable grids. Add YAML frontmatter for databases, or drop to HTML + Go templates for full control. | ||
| - **Git-native and self-hosted.** Plain text in a repo. Version history, offline access, no subscriptions. |
There was a problem hiding this comment.
PR description says to keep the same points, but this bullet drops “collaboration” (and previously mentioned benefits like search). If those are still intended selling points, consider reintroducing them here in a concise way to avoid losing a core claim.
README.md
Outdated
| - **8 data sources out of the box.** SQLite, PostgreSQL, REST APIs, JSON, CSV, shell commands, markdown files, and WASM. Point at your existing infrastructure — a database, a cluster, an internal API — and have a working UI without writing any glue code. | ||
| - **Git-native and self-hosted.** Plain text in a repo means you get version history, search, offline access, and collaboration for free. No subscriptions, no platform lock-in. | ||
| - **Made for disposable software.** The admin panel for this sprint. The tracker for that hiring round. The runbook for on-call week. Software you'd never justify scaffolding a React project for, but that's genuinely useful for a few days or weeks. When you're done, the markdown is still readable on its own. | ||
| Most internal tools don't need a framework. Tinkerdown replaces the scaffolding with a single markdown file — data sources in YAML, layout in markdown, interactions via HTML attributes. |
There was a problem hiding this comment.
The heading/PR goal says the copy should be concise and factual, but this sentence is a broad, opinionated claim (“Most internal tools don't need a framework”). Consider softening to a verifiable statement (e.g., “Many internal tools…” or framing it as a design goal) so the section stays factual.
- Remove opinionated opener ("Most internal tools don't need a framework")
- Clarify "no dependencies" to "no node_modules" for precision
- Rewrite AI bullet to describe concrete properties instead of asserting outcomes
- Restore dropped "search" and "collaboration" to Git-native bullet
https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81
Remove the ranty intro paragraph and tighten each bullet to one or two sentences. Keep the same points, lose the sermon.
https://claude.ai/code/session_01NhTvt3NdnN6vmUpwimuM81