From 3bbc877d4c42917d494688ddcfe2dd3b1daf7f62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?M=C3=A5rten=20Angner?= Date: Thu, 11 Dec 2025 14:01:31 +0100 Subject: [PATCH] fix(wds): Move repository structure decision to naming stage (Step 2.2) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- .../tutorial-02.md | 83 +++++++++++++++---- 1 file changed, 68 insertions(+), 15 deletions(-) diff --git a/src/modules/wds/course/module-02-installation-setup/tutorial-02.md b/src/modules/wds/course/module-02-installation-setup/tutorial-02.md index 7197af4f..01d19bd8 100644 --- a/src/modules/wds/course/module-02-installation-setup/tutorial-02.md +++ b/src/modules/wds/course/module-02-installation-setup/tutorial-02.md @@ -57,10 +57,65 @@ By the end of this tutorial: ### 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:** - Use lowercase with hyphens - Descriptive and specific -- Examples: `dog-walker-app`, `recipe-sharing-platform`, `fitness-tracker-specs` +- Examples: `dog-walker-app` OR `dog-walker-app-specs` **Description:** - 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 -**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. -### 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/ ├── 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-code/ ← Separate code repo +my-project-specs/ ← This repo (specifications only) + ← 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 @@ -193,7 +246,7 @@ git --version If you see a version number → you're good! 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! ---