The-Data-Nerds · tri-pti · Jul 8, 2026
diff --git a/.github/scripts/check-doc-drift.sh b/.github/scripts/check-doc-drift.sh
@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# QUICKSTART.md is the canonical onboarding guide (see
+# CONTRIBUTING.md#-documentation-structure). This fails CI if onboarding
+# workflow steps get copy-pasted back into the other docs instead of
+# linking to QUICKSTART.md.
+set -euo pipefail
+
+CANONICAL_FILE="QUICKSTART.md"
+CHECK_FILES=("README.md" "FAQ.md" "CONTRIBUTING.md")
+
+# Workflow-step commands/markers that must only live in QUICKSTART.md
+PATTERNS=(
+  'git checkout -b add-your-name'
+  'git commit --amend -m'
+  'git push -f origin add-your-name'
+  '<<<<<<< HEAD'
+)
+
+failed=0
+
+for file in "${CHECK_FILES[@]}"; do
+  for pattern in "${PATTERNS[@]}"; do
+    if grep -qF -- "$pattern" "$file"; then
+      echo "::error file=$file::Found onboarding-workflow content ('$pattern') that duplicates $CANONICAL_FILE. Link to $CANONICAL_FILE instead of repeating workflow steps (see CONTRIBUTING.md#-documentation-structure)."
+      failed=1
+    fi
+  done
+done
+
+if [ "$failed" -ne 0 ]; then
+  echo ""
+  echo "Documentation consistency check failed. See CONTRIBUTING.md#-documentation-structure for ownership rules."
+  exit 1
+fi
+
+echo "Documentation consistency check passed."
diff --git a/.github/workflows/ci-validation.yml b/.github/workflows/ci-validation.yml
@@ -17,6 +17,9 @@ jobs:
         with:
           fetch-depth: 0
 
+      - name: Check for Duplicated Onboarding Instructions
+        run: bash .github/scripts/check-doc-drift.sh
+
       - name: Run Markdown Lint Check
         uses: davidanson/markdownlint-cli2-action@v23
         with:

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -66,6 +66,19 @@ Write clear and descriptive commit messages:
 - ❌ Avoid: "Update"
 - ❌ Avoid: "Changes"
 
+## 📑 Documentation Structure
+
+To avoid conflicting onboarding instructions across files, each doc has a defined scope:
+
+| Document | Purpose | Owns |
+|----------|---------|------|
+| [QUICKSTART.md](QUICKSTART.md) | **Canonical onboarding guide** | All fork/clone/branch/commit/push/PR steps and their troubleshooting |
+| [README.md](README.md) | Project landing page | Project overview, contributor list, high-level links |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | Contribution policy | PR requirements, commit conventions, code of conduct, this table |
+| [FAQ.md](FAQ.md) | Extended Q&A | Questions outside the core workflow — any workflow-step question links to QUICKSTART.md instead of repeating steps |
+
+**Rule of thumb:** if you're changing how someone forks, clones, branches, commits, pushes, or opens a PR, edit `QUICKSTART.md` only. Other docs should link to it, not restate it.
+
 ## Code of Conduct
 
 ### Our Standards

diff --git a/FAQ.md b/FAQ.md
@@ -51,30 +51,7 @@ If other people merge their Pull Requests while you are working, your fork can f
 ### ❓ I got a "Merge Conflict" in my Pull Request. What should I do?
 A merge conflict happens when two people edit the same line of the same file, and Git doesn't know which version to keep. Don't worry, it's very easy to fix!
 
-1. Make sure your local repository is updated (see the sync steps above).
-2. Checkout your working branch:
-   ```bash
-   git checkout add-your-name
-   ```
-3. Merge the updated main branch into your working branch:
-   ```bash
-   git merge main
-   ```
-4. Open the conflicting file (`README.md` or `QUICKSTART.md`) in your text editor. Look for conflict markers:
-   ```markdown
-   <<<<<<< HEAD
-   - [Your Name](https://github.com/YOUR-USERNAME)
-   =======
-   - [Someone Else](https://github.com/someone-else)
-   >>>>>>> main
-   ```
-5. Edit the file to keep **both** names (make sure to delete the `<<<<<<<`, `=======`, and `>>>>>>>` markers).
-6. Save the file, add, commit, and push:
-   ```bash
-   git add README.md
-   git commit -m "Fix merge conflict"
-   git push origin add-your-name
-   ```
+See **[QUICKSTART.md → 🆘 Stuck?](QUICKSTART.md#-stuck)** for the full step-by-step walkthrough.
 
 ---
 

diff --git a/QUICKSTART.md b/QUICKSTART.md
@@ -10,6 +10,10 @@
 
 ---
 
+> 📌 **This is the canonical onboarding guide.** All fork → clone → branch → commit → push → PR steps and their troubleshooting live here. Other docs (README, CONTRIBUTING, FAQ) link to this file instead of repeating the steps — please keep it that way when editing docs. See [CONTRIBUTING.md → Documentation Structure](CONTRIBUTING.md#-documentation-structure) for the full ownership breakdown.
+
+---
+
 ## Prerequisites ✅
 
 - [ ] [GitHub account](https://github.com/signup)
@@ -288,8 +292,21 @@ You should see your PR with a number (e.g., `#42`).
 * Add and commit: `git add README.md && git commit -m "Fix merge conflict"`
 * Push again: `git push origin add-your-name`
 
+**My terminal/command prompt doesn't work**
+→ **Windows:** Use Git Bash (installed with Git) or PowerShell
+→ **Mac:** Use Terminal (find it in Applications > Utilities)
+→ **Linux:** Use your default terminal (Ctrl+Alt+T)
+
+**I made a mistake in my commit**
+→ Make the correction, then:
+
+```bash
+git add README.md
+git commit --amend -m "Add [Your Name] to contributors list"
+git push -f origin add-your-name
+```
+
 **Need more help?**
-→ Check `README.md` for detailed step-by-step instructions
 → See `FAQ.md` for common questions
 → [Open an issue](../../issues) if you're still stuck
 

diff --git a/README.md b/README.md
@@ -111,56 +111,7 @@ _Your name will appear here once your PR is merged!_
 
 ## 🆘 Stuck? Get Help!
 
-### Common Issues & Solutions
-
-<details>
-<summary><b>❌ "Git is not recognized" or "command not found"</b></summary>
-
-**Solution:** Git isn't installed. Download it from [git-scm.com](https://git-scm.com/downloads) and restart your terminal.
-
-</details>
-
-<details>
-<summary><b>❌ "Permission denied" when pushing</b></summary>
-
-**Solution:** You might not have permission to push to the original repo. Make sure you:
-
-1. Forked the repository first
-2. Cloned YOUR fork, not the original repository
-3. The URL should contain YOUR username
-</details>
-
-<details>
-<summary><b>❌ "Merge conflict" in Pull Request</b></summary>
-
-**Solution:** Someone else added their name in the same spot. Don't panic!
-
-1. Pull the latest changes: `git pull origin main`
-2. Fix the conflicts in README.md (remove the `<<<<`, `====`, `>>>>` markers)
-3. Add and commit: `git add README.md && git commit -m "Fix merge conflict"`
-4. Push again: `git push origin add-your-name`
-</details>
-
-<details>
-<summary><b>❌ My terminal/command prompt doesn't work</b></summary>
-
-**Solutions:**
-
-- **Windows:** Use Git Bash (installed with Git) or PowerShell
-- **Mac:** Use Terminal (find it in Applications > Utilities)
-- **Linux:** Use your default terminal (Ctrl+Alt+T)
-</details>
-
-<details>
-<summary><b>❌ I made a mistake in my commit</b></summary>
-
-**Solution:** You can fix it!
-
-1. Make the correction in README.md
-2. Stage: `git add README.md`
-3. Amend the commit: `git commit --amend -m "Add [Your Name] to contributors list"`
-4. Force push: `git push -f origin add-your-name`
-</details>
+Ran into "Git not recognized", "Permission denied" when pushing, a merge conflict, a terminal issue, or a bad commit? All of that is covered in **[QUICKSTART.md → 🆘 Stuck?](QUICKSTART.md#-stuck)** — the canonical troubleshooting guide for this project.
 
 ### Still Need Help?