fix(wds): Move repository structure decision to naming stage (Step 2.2)

Critical UX improvement: Decision happens at the RIGHT moment.

Changes to Step 2.2 (Repository Settings):
- ADDED: Comprehensive 'Single vs Separate Repo' decision framework
- Decision now happens DURING naming (not after)
- Clear naming convention: 'my-project' vs 'my-project-specs'

Single Repository Use Cases:
✅ Close to development team
✅ Simple, direct communication needed
✅ Building the project yourself
✅ Working closely with other designers
✅ Small team with full ownership
✅ Rapid iteration and feedback

Separate Repository Use Cases:
✅ Corporate or enterprise environment
✅ Specifications serve multiple products/platforms
✅ Development team has many developers
✅ Extensive or complex codebase
✅ Clear handoff boundaries needed
✅ Design and dev have separate workflows

Changes to Step 2.3:
- Acknowledge decision was made
- Remind about implications

Changes to Step 4.1:
- SIMPLIFIED: Just recap the decision made in Step 2
- No longer presenting options (already decided!)
- Cleaner flow

Reasoning:
Repository NAME determines structure. The decision must happen when
naming the repository, not later. This is when GitHub asks 'what do
you want to call this?' - that's the natural decision point.

Benefits:
- Decision at natural moment (when naming)
- Clear naming conventions prevent confusion
- Users understand implications before creating
- No 'oops, I named it wrong' moments
- Professional guidance on when to use each approach
This commit is contained in:
Mårten Angner 2025-12-11 14:01:31 +01:00
parent b13fef783a
commit 3bbc877d4c
1 changed files with 68 additions and 15 deletions

View File

@ -57,10 +57,65 @@ By the end of this tutorial:
### 2.2 Repository Settings ### 2.2 Repository Settings
**IMPORTANT: Your naming choice determines your structure!**
### Single Repo or Separate Specs Repo?
**Option A: Single Repository**
**Name it simply:**
- `dog-walker-app`
- `recipe-platform`
- `fitness-tracker`
**Structure:**
```
dog-walker-app/
├── docs/ ← Your WDS specifications
└── src/ ← Code
```
**Use when:**
- ✅ You're close to the development team
- ✅ You want simple, direct communication
- ✅ You're building the whole project yourself
- ✅ Working closely with other designers
- ✅ Small team with full ownership
- ✅ Rapid iteration and feedback
**Option B: Separate Specifications Repository**
**Name with `-specs` suffix:**
- `dog-walker-app-specs`
- `recipe-platform-specs`
- `fitness-tracker-specs`
**Structure:**
```
dog-walker-app-specs/ ← This repo (specifications only)
dog-walker-app/ ← Separate code repo
```
**Use when:**
- ✅ Corporate or enterprise environment
- ✅ Specifications serve multiple products/platforms
- ✅ Development team has many developers
- ✅ Extensive or complex codebase
- ✅ Clear handoff boundaries needed
- ✅ Design and dev have separate workflows
**For this tutorial:**
- Beginners: Use **Option A** (single repo like `dog-walker-app`)
- Corporate/Enterprise: Use **Option B** (separate like `dog-walker-app-specs`)
**Choose your name now based on your situation!**
---
**Repository Name:** **Repository Name:**
- Use lowercase with hyphens - Use lowercase with hyphens
- Descriptive and specific - Descriptive and specific
- Examples: `dog-walker-app`, `recipe-sharing-platform`, `fitness-tracker-specs` - Examples: `dog-walker-app` OR `dog-walker-app-specs`
**Description:** **Description:**
- Short one-liner about your project - Short one-liner about your project
@ -81,7 +136,9 @@ Click the green **"Create repository"** button
**✅ Checkpoint:** You see your new repository with a README file **✅ Checkpoint:** You see your new repository with a README file
**Note:** We'll discuss single vs. separate repository structure in Step 4 before cloning! **Remember your choice:**
- Single repo (`my-project`)? Specs and code together
- Separate repo (`my-project-specs`)? You'll create a second repo for code later
--- ---
@ -133,28 +190,24 @@ Cursor will ask you a few questions:
**Good news:** You don't need to install anything manually! Modern IDEs like Cursor handle this for you. **Good news:** You don't need to install anything manually! Modern IDEs like Cursor handle this for you.
### 4.1 Important Repository Decision First ### 4.1 Recap: Your Repository Structure
**Before cloning, understand your options:** **You already decided this in Step 2 when naming your repo!**
**Option A: Single Repository (Recommended for beginners)** **Single repo (named `my-project`):**
``` ```
my-project/ my-project/
├── docs/ ← Your WDS specifications ├── docs/ ← Your WDS specifications
└── src/ ← Code (if building yourself) └── src/ ← Code lives here too
``` ```
**Pros:** Everything in one place, simpler
**Best for:** Solo projects, learning, full ownership
**Option B: Separate Repositories** **Separate repo (named `my-project-specs`):**
``` ```
my-project-specs/ ← WDS specifications (this repo) my-project-specs/ ← This repo (specifications only)
my-project-code/ ← Separate code repo ← Create separate code repo later
``` ```
**Pros:** Clean separation, easier handoff to developers
**Best for:** Client projects, team collaboration
**For this tutorial, we'll use Option A (single repo).** **For this tutorial, we assume single repo** (`dog-walker-app`)
### 4.2 Let Cursor Install Git Automatically ### 4.2 Let Cursor Install Git Automatically
@ -193,7 +246,7 @@ git --version
If you see a version number → you're good! If you see a version number → you're good!
If not → Continue to Step 5, Cursor will prompt you. If not → Continue to Step 5, Cursor will prompt you.
**✅ Checkpoint:** You understand single vs separate repos, ready for Step 5! **✅ Checkpoint:** Ready to clone your repository in Step 5!
--- ---