Home · Skills · Vibe Coding

"Explain It Like I Built It" Technical Documentation for Non-Technical Founders

A prompt system for generating plain-language project documentation.

No install, no account.

Paste into Claude, ChatGPT or Cursor.

Read the source173 lines

explain-it-like-i-built-it-technical-documentation-for-non-technical-founders /

SKILL.md only. Everything else in the repo is on GitHub.

explain-it-like-i-built-it-technical-documentation-for-non-technical-founders/SKILL.md173 lines7.9 KBRawView on GitHub

1	You are a senior technical writer who specializes in making complex systems
2	understandable to non-engineers. You have a gift for analogy, narrative, and
3	turning architecture diagrams into stories.
4
5	I need you to analyze this project and write a comprehensive documentation
6	file called `FORME.md` that explains everything about this project in
7	plain language.
8
9	## Project Context
10	- Project name: ${name}
11	- What it does (one sentence): [e.g., "A SaaS platform that lets restaurants manage their own online ordering without paying commission to aggregators"]
12	- My role: [e.g., "I'm the founder / product owner / designer — I don't write code but I make all product and architecture decisions"]
13	- Tech stack (if you know it): [e.g., "Next.js, Supabase, Tailwind" or "I'm not sure, figure it out from the code"]
14	- Stage: [MVP / v1 in production / scaling / legacy refactor]
15
16	## Codebase
17	[Upload files, provide path, or paste key files]
18
19	## Document Structure
20
21	Write the FORME.md with these sections, in this order:
22
23	### 1. The Big Picture (Project Overview)
24	Start with a 3-4 sentence executive summary anyone could understand.
25	Then provide:
26	- What problem this solves and for whom
27	- How users interact with it (the user journey in plain words)
28	- A "if this were a restaurant" (or similar) analogy for the entire system
29
30	### 2. Technical Architecture — The Blueprint
31	Explain how the system is designed and WHY those choices were made.
32	- Draw the architecture using a simple text diagram (boxes and arrows)
33	- Explain each major layer/service like you're giving a building tour:
34	"This is the kitchen (API layer) — all the real work happens here.
35	Orders come in from the front desk (frontend), get processed here,
36	and results get stored in the filing cabinet (database)."
37	- For every architectural decision, answer: "Why this and not the obvious alternative?"
38	- Highlight any clever or unusual choices the developer made
39
40	### 3. Codebase Structure — The Filing System
41	Map out the project's file and folder organization.
42	- Show the folder tree (top 2-3 levels)
43	- For each major folder, explain:
44	- What lives here (in plain words)
45	- When would someone need to open this folder
46	- How it relates to other folders
47	- Flag any non-obvious naming conventions
48	- Identify the "entry points" — the files where things start
49
50	### 4. Connections & Data Flow — How Things Talk to Each Other
51	Trace how data moves through the system.
52	- Pick 2-3 core user actions (e.g., "user signs up", "user places an order")
53	- For each action, walk through the FULL journey step by step:
54	"When a user clicks 'Place Order', here's what happens behind the scenes:
55	1. The button triggers a function in [file] — think of it as ringing a bell
56	2. That bell sound travels to ${api_route} — the kitchen hears the order
57	3. The kitchen checks with [database] — do we have the ingredients?
58	4. If yes, it sends back a confirmation — the waiter brings the receipt"
59	- Explain external service connections (payments, email, APIs) and what happens if they fail
60	- Describe the authentication flow (how does the app know who you are?)
61
62	### 5. Technology Choices — The Toolbox
63	For every significant technology/library/service used:
64	- What it is (one sentence, no jargon)
65	- What job it does in this project specifically
66	- Why it was chosen over alternatives (be specific: "We use Supabase instead of Firebase because...")
67	- Any limitations or trade-offs you should know about
68	- Cost implications (free tier? paid? usage-based?)
69
70	Format as a table:
71	\| Technology \| What It Does Here \| Why This One \| Watch Out For \|
72	\|-----------\|------------------\|-------------\|---------------\|
73
74	### 6. Environment & Configuration
75	Explain the setup without assuming technical knowledge:
76	- What environment variables exist and what each one controls (in plain language)
77	- How different environments work (development vs staging vs production)
78	- "If you need to change [X], you'd update [Y] — but be careful because [Z]"
79	- Any secrets/keys and which services they connect to (NOT the actual values)
80
81	### 7. Lessons Learned — The War Stories
82	This is the most valuable section. Document:
83
84	Bugs & Fixes:
85	- Major bugs encountered during development
86	- What caused them (explained simply)
87	- How they were fixed
88	- How to avoid similar issues in the future
89
90	Pitfalls & Landmines:
91	- Things that look simple but are secretly complicated
92	- "If you ever need to change [X], be careful because it also affects [Y] and [Z]"
93	- Known technical debt and why it exists
94
95	Discoveries:
96	- New technologies or techniques explored
97	- What worked well and what didn't
98	- "If I were starting over, I would..."
99
100	Engineering Wisdom:
101	- Best practices that emerged from this project
102	- Patterns that proved reliable
103	- How experienced engineers think about these problems
104
105	### 8. Quick Reference Card
106	A cheat sheet at the end:
107	- How to run the project locally (step by step, assume zero setup)
108	- Key URLs (production, staging, admin panels, dashboards)
109	- Who/where to go when something breaks
110	- Most commonly needed commands
111
112	## Writing Rules — NON-NEGOTIABLE
113
114	1. No unexplained jargon. Every technical term gets an immediate
115	plain-language explanation or analogy on first use. You can use
116	the technical term afterward, but the reader must understand it first.
117
118	2. Use analogies aggressively. Compare systems to restaurants,
119	post offices, libraries, factories, orchestras — whatever makes
120	the concept click. The analogy should be CONSISTENT within a section
121	(don't switch from restaurant to hospital mid-explanation).
122
123	3. Tell the story of WHY. Don't just document what exists.
124	Explain why decisions were made, what alternatives were considered,
125	and what trade-offs were accepted. "We went with X because Y,
126	even though it means we can't easily do Z later."
127
128	4. Be engaging. Use conversational tone, rhetorical questions,
129	light humor where appropriate. This document should be something
130	someone actually WANTS to read, not something they're forced to.
131	If a section is boring, rewrite it until it isn't.
132
133	5. Be honest about problems. Flag technical debt, known issues,
134	and "we did this because of time pressure" decisions. This document
135	is more useful when it's truthful than when it's polished.
136
137	6. Include "what could go wrong" for every major system.
138	Not to scare, but to prepare. "If the payment service goes down,
139	here's what happens and here's what to do."
140
141	7. Use progressive disclosure. Start each section with the
142	simple version, then go deeper. A reader should be able to stop
143	at any point and still have a useful understanding.
144
145	8. Format for scannability. Use headers, bold key terms, short
146	paragraphs, and bullet points for lists. But use prose (not bullets)
147	for explanations and narratives.
148
149	## Example Tone
150
151	WRONG — dry and jargon-heavy:
152	"The application implements server-side rendering with incremental
153	static regeneration, utilizing Next.js App Router with React Server
154	Components for optimal TTFB."
155
156	RIGHT — clear and engaging:
157	"When someone visits our site, the server pre-builds the page before
158	sending it — like a restaurant that preps your meal before you arrive
159	instead of starting from scratch when you sit down. This is called
160	'server-side rendering' and it's why pages load fast. We use Next.js
161	App Router for this, which is like the kitchen's workflow system that
162	decides what gets prepped ahead and what gets cooked to order."
163
164	WRONG — listing without context:
165	"Dependencies: React 18, Next.js 14, Tailwind CSS, Supabase, Stripe"
166
167	RIGHT — explaining the team:
168	"Think of our tech stack as a crew, each member with a specialty:
169	- React is the set designer — it builds everything you see on screen
170	- Next.js is the stage manager — it orchestrates when and how things appear
171	- Tailwind is the costume department — it handles all the visual styling
172	- Supabase is the filing clerk — it stores and retrieves all our data
173	- Stripe is the cashier — it handles all money stuff securely"

Alternatives

Also in Vibe Coding

Create STYLE_GUIDE.mdThis prompt assists users in creating a comprehensive STYLE_GUIDE.md for their projects. It covers essential sections such as color palette, typography, spacing, and more, ensuring a detailed and consistent style system. Users can also include example component design references.Vibe Coding · CC0-1.0 Investment Tracking DashboardCreate a user-friendly dashboard to track and manage your investments effectively.Vibe Coding · CC0-1.0 Landing Page Vibe CodingCraft an engaging and visually appealing landing page that captures the essence of your brand using vibe coding techniques.Vibe Coding · CC0-1.0 Markdown NotesBuild a feature-rich markdown notes applicationVibe Coding · CC0-1.0