처음 온 사람을 데려가는 길, 튜토리얼 - 개발자를 위한 기술문서 입문 ep.02

튜토리얼은 가장 많이 쓰이고, 가장 자주 망가지는 문서입니다. 그리고 망가지는 방식은 거의 일정합니다. 설명을 하려 든다는 것입니다.

튜토리얼을 쓰다 보면 “이 개념은 X라는 배경이 있어서…” “이 옵션은 사실 …” 같은 문장이 슬그머니 끼어듭니다. 작성자는 친절하다고 느끼지만, 학습자는 길을 잃습니다. 학습자가 원하는 건 지식이 아니라 경험입니다. 무언가 동작했다는 경험, 자기가 만들었다는 감각.

이번 편의 관점은 다음 한 문장으로 압축됩니다. 튜토리얼은 설명하는 글이 아니라 경험을 설계하는 글입니다.

튜토리얼과 하우투를 가르는 선

가장 자주 헷갈리는 두 종류부터 정리합니다. 둘 다 실용 쪽에 있지만 독자가 다릅니다.

튜토리얼과 하우투 가이드를 두 컬럼으로 비교한 다이어그램. 왼쪽 튜토리얼(Tutorial)은 학습 + 실용 분면. 독자는 처음 본 사람, 목표는 "무언가 만들어봤다"는 경험, 결과는 눈에 보이는 산출물, 분기는 없음(한 길로 끝까지), 화법은 "같이 해봅시다". 오른쪽 하우투 가이드(How-to Guide)는 작업 + 실용 분면. 독자는 목적이 있는 사람, 목표는 "이 일을 해냈다"는 완료, 결과는 문제 해결, 분기는 있음(상황에 따라 갈라짐), 화법은 "이렇게 하면 됩니다".

이 차이가 글의 구조 전체를 결정합니다.

튜토리얼은 분기를 만들지 않습니다. “Mac이면 X, Windows면 Y” 같은 분기가 들어오는 순간 학습자는 자기가 어느 길에 있는지 확인하려 멈춥니다. 한 길로만 갑니다.

하우투는 분기를 만듭니다. “프로덕션이면 X, 스테이징이면 Y” 같은 분기가 자연스럽습니다. 독자는 자기 상황을 알고 와있기 때문입니다.

튜토리얼은 선택을 강요하지 않습니다. “이 옵션을 켤지는 취향입니다”라는 문장은 학습자를 멈춰 세웁니다. 선택지가 있다면 작성자가 골라주고 다음으로 넘어갑니다.

하우투는 선택지를 보여줍니다. 독자가 자기 상황에 맞는 걸 고를 수 있어야 하니까요.

학습자 여정 설계

튜토리얼을 쓸 때 가장 먼저 그려야 하는 건 학습자가 어떤 순서로 작은 성공을 쌓는가입니다.

튜토리얼의 학습자 여정 흐름도. 가로로 다섯 단계가 이어진다. 1단계 진입(왜 이걸 해보는가), 2단계 환경(설치, 첫 실행 확인), 3단계 작은 성공(10분 안에 동작 확인), 4단계 확장(개념을 하나씩 덧붙임), 5단계 완성된 결과물(내가 만들었다는 산출물, 기억은 여기서 만들어진다). 다이어그램 아래에는 빨간 점선과 함께 금지 사항 세 가지가 적혀 있다: 금지 1 단계별 분기(Mac이면 X, Windows면 Y), 금지 2 옵션 설명(이 플래그는…), 금지 3 추가 학습 거리(관심이 있다면…).

이 다섯 단계를 차례로 봅니다.

1. 진입 — 왜 해보는지를 두 문장 안에

튜토리얼의 첫 단락은 학습자에게 “이걸 따라가면 무엇을 얻는가”를 줘야 합니다. 추상적인 약속은 안 됩니다. 구체적인 결과물의 이미지가 필요합니다.

약한 진입:
> 이 튜토리얼에서는 Express의 기본을 배웁니다.

강한 진입:
> 이 튜토리얼에서는 Express로 "투두 리스트"를 만들어봅니다.
> 끝나면 브라우저에서 작동하는 작은 웹 앱이 손에 남습니다.

후자는 결과의 이미지가 잡힙니다. 학습자는 자기가 어디로 향하는지 알면 길고 지루한 단계도 견딥니다.

2. 환경 — 최소한의 준비

설치, 환경 변수, 의존성 같은 것들. 여기서 학습자가 가장 자주 떨어집니다. 두 가지를 지킵니다.

최소한으로 줄입니다. 튜토리얼에 필요한 만큼만. “혹시 나중에 필요할지도 모르니” 같은 이유로 패키지를 더 까는 건 금기입니다.

검증 단계를 둡니다. 설치 후에 동작을 확인하는 명령을 반드시 넣습니다.

# 설치
npm install -g express-generator

# 확인 — 버전이 나타나면 OK
express --version

학습자가 다음 단계로 넘어가기 전 자기가 어디에 있는지 알게 해주는 작은 신호입니다.

환경 자체를 우회하는 방법

가장 좋은 환경 단계는 없는 환경 단계입니다. 학습자가 자기 컴퓨터를 건드리지 않고 따라갈 수 있다면 이탈률은 극적으로 떨어집니다.

StackBlitz·CodeSandbox·Replit: Node·Python·React 같은 런타임을 브라우저 안에서 띄워줍니다. 튜토리얼 첫 단락에 “이 버튼을 누르면 환경이 준비됩니다” 한 줄을 넣어두면 환경 단계 전체를 건너뜁니다.
GitHub Codespaces·Gitpod: 저장소 한쪽에 .devcontainer/를 두면 학습자가 자기 IDE를 그대로 클라우드로 옮겨 받습니다. 사내 튜토리얼·OSS 컨트리뷰션 가이드에서 특히 강력합니다.
Docker 한 줄: 컨테이너 한 줄로 모든 의존성을 가둘 수 있으면 docker run --rm -it ...로 시작하는 튜토리얼이 됩니다. 학습자의 호스트에 흔적을 안 남기는 점도 좋습니다.

이 우회 수단이 가능하지 않을 때만 OS·언어 버전 분기를 글에 들입니다. 그리고 분기는 가능하면 튜토리얼 본문 바깥(별도 페이지·접기/펴기 블록)으로 빼냅니다. 본문 한가운데서 분기하면 학습자는 자기 길을 다시 찾는 데 인지 자원을 씁니다.

3. 작은 성공 — 10분 안에 무언가 돌게

튜토리얼의 심장입니다. 첫 10분 안에 학습자에게 “어, 됐다” 하는 순간을 만들어줘야 합니다. 이 순간이 없으면 학습자는 떠납니다. 있으면 끝까지 따라옵니다.

작은 성공의 기준은 두 가지입니다. 눈에 보여야 하고, 학습자가 무언가 한 결과여야 합니다. “터미널에 OK가 찍히는 것”도 작은 성공이고, “브라우저에 페이지가 뜨는 것”도 작은 성공입니다.

약한 작은 성공:
> 설정 파일이 만들어집니다.

강한 작은 성공:
> 브라우저에서 http://localhost:3000을 열면
> "Welcome to Express"가 보입니다.

후자는 학습자가 눈으로 확인합니다. 그게 결정적입니다.

작은 성공을 어디에 두는가 — 공개 튜토리얼 세 곳

작은 성공 지점이 어디에 박혀 있는지가 좋은 튜토리얼을 가르는 결정적 지표입니다. 잘 알려진 셋을 봅니다.

Django의 “Polls” 튜토리얼: Part 1 초반에 python manage.py runserver → 브라우저에서 로켓이 떠오르는 “Congratulations!” 페이지를 보는 순간이 옵니다. 모델·뷰·템플릿이 등장하기 전에 이미 한 번 성공한 상태입니다. 이후 단계는 그 토대 위에 기능을 올립니다.
The Rust Book 1장: cargo new hello_cargo → cargo run → Hello, world!까지 10분 안에 끝납니다. 소유권·라이프타임 같은 개념은 이 첫 성공 이후로 미뤄집니다.
Astro의 “Build a blog” 튜토리얼: Unit 1에서 프로젝트를 만들고 npm run dev → 브라우저에서 “Astro” 글자만 있는 시작 페이지를 확인합니다. 자기 페이지·컴포넌트·콘텐츠 콜렉션·MDX는 모두 이 첫 성공 뒤 Unit 2부터 차례로 등장합니다.

세 사례의 공통점은 프레임워크의 철학을 가르치기 전에 학습자에게 동작하는 결과를 먼저 안긴다는 것입니다. 첫 성공 이전의 단락은 모두 환경이고, 첫 성공 이후가 진짜 튜토리얼입니다.

4. 확장 — 한 번에 한 개념

여기서 가장 자주 망가집니다. 작성자는 익숙해서 한 단계에 여러 개념을 욱여넣지만, 학습자는 그걸 못 따라옵니다.

규칙은 단순합니다. 한 단계에 한 가지 새로운 것.

약한 확장:
> 라우터를 만들고, 미들웨어를 추가하고, 템플릿 엔진을 설정하고…

강한 확장:
> [단계 4] 라우터 만들기
> [단계 5] 만든 라우터에 미들웨어 추가하기
> [단계 6] 라우터에서 템플릿 엔진 쓰기

각 단계 끝에는 지금 무엇이 가능해졌는지를 한 줄로 보여줍니다. 작은 성공의 축소판입니다.

짧은 시나리오 — React 튜토리얼 5단계의 인지 부하

가상의 신입 개발자 파이가 자기 팀의 React 튜토리얼을 처음부터 따라간다고 상상해봅니다. 작성자가 5단계로 나눠둔 글입니다.

1단계. 컴포넌트 한 개 만들기
function Hello() { return <h1>안녕</h1> }. 학습자에게 새로운 건 JSX 하나뿐입니다. 다른 건 함수, 문자열, return — 다 알고 있는 것들입니다. 파이는 5분 안에 한 번 성공합니다.
2단계. props로 이름 받기
<Hello name="파이" />. 새로운 건 props 하나. JSX는 이미 1단계에서 익숙해졌습니다. 파이는 자기 이름을 화면에 띄우고 한 번 더 작게 성공합니다.
3단계. useState로 카운터
새로운 건 상태(state) 하나. props는 이미 익숙합니다. 카운터가 올라가는 걸 보며 또 한 번 성공합니다.
4단계. 이벤트 핸들러로 입력 받기
새로운 건 이벤트 하나. 상태 변경은 이미 익숙합니다.
5단계. useEffect로 외부 데이터 가져오기
새로운 건 부수 효과(effect) 하나.

이 다섯 단계의 핵심은 매 단계마다 새 개념이 정확히 한 개라는 것입니다. 만약 1단계에서 JSX·props·state를 한꺼번에 던졌다면 파이는 5분 안에 떠났을 것입니다. 작성자가 새 개념 한 개씩만 등장시키는 규율을 지키면, 학습자의 인지 부하는 매 단계 비슷한 수준으로 유지됩니다. 이게 한 번에 한 개념의 진짜 의미입니다.

5. 완성 — 내가 만들었다는 산출물

튜토리얼은 기억으로 남아야 합니다. 기억은 완성된 결과물 위에 만들어집니다. 그래서 마지막은 “완성된 결과물”에서 끝나야 합니다.

여기까지 따라온 학습자에게 다음 두 가지를 줍니다.

자신감의 확인. “당신은 이걸 만들었습니다. 이런 것까지 할 수 있게 된 것입니다.”

다음 길의 안내. “이걸 더 발전시키려면…”, “유사한 개념을 깊이 알려면…”. 다만 지금 이 글에서 가르치려 들지는 않습니다. 다음 글로 보냅니다.

튜토리얼이 자주 무너지는 지점

다섯 가지만 짚어둡니다.

설명하려 든다
”이건 사실 ~의 약자로 …의 의미를 가집니다.” 같은 문장이 끼어듭니다. 설명이 필요한 학습자는 익스플레네이션을 읽으러 갑니다. 튜토리얼에선 그렇구나, 다음으로 넘어갑니다.
선택지를 준다
”여기서 A를 쓸 수도 있고 B를 쓸 수도 있는데…”는 학습자를 멈춥니다. 작성자가 하나를 골라줍니다. 이유는 짧게.
환경에 의존한다
작성자의 로컬에서만 되는 명령어, 회사 인트라넷에서만 가는 URL. 이런 게 들어가면 학습자는 어디서 막혔는지도 모릅니다.
검증 단계를 빼먹는다
학습자는 자기가 잘 가고 있는지 모릅니다. 각 단계 끝에 지금 무엇이 보여야 정상인가를 둡니다.
너무 많은 걸 가르치려 한다
한 튜토리얼은 한 가지 결과물에 집중합니다. 욕심이 나면 두 번째 튜토리얼로 분리합니다.

좋은 예와 나쁜 예

같은 내용을 두 가지 방식으로 써본 짧은 예시입니다.

나쁜 예

## Express 시작하기

Express는 Node.js 기반의 미니멀한 웹 프레임워크입니다.
2010년에 TJ Holowaychuk이 처음 만들었으며, 현재는 OpenJS Foundation 산하에서
관리되고 있습니다. 비슷한 프레임워크로는 Koa, Fastify, Hapi 등이 있는데
각각의 철학이 다릅니다.

설치하려면 Node가 필요한데, Node 버전은 16 이상을 권장하지만 18이나 20도
괜찮고, 기업 환경에서는 LTS를 쓰는 게 일반적입니다. 패키지 매니저는
npm을 쓰거나 yarn을 쓰거나 pnpm을 쓸 수 있는데, 각각의 장단이 있습니다.

```bash
npm install express
```

그러면 설치가 됩니다. 다음으로 라우터를 만들어야 하는데…

문제: 첫 두 단락이 역사 수업이고, 학습자는 아직 한 줄도 못 짰습니다. 패키지 매니저 선택지에서 멈춥니다. 결과물이 무엇인지에 대한 그림이 없습니다.

좋은 예

## Express로 첫 웹 페이지 띄우기

이 튜토리얼에서는 Express로 "Hello, 이름!"을 띄우는 작은 웹 앱을 만듭니다.
끝나면 브라우저에 자기 이름이 환영 인사로 뜨는 페이지가 손에 남습니다.

### 1. 환경

Node 18 이상이 필요합니다. 다음 명령으로 확인합니다.

```bash
node --version
# v18.0.0 이상이면 OK
```

### 2. 프로젝트 만들기

```bash
mkdir hello-express && cd hello-express
npm init -y
npm install express
```

### 3. 첫 서버

\`app.js\` 파일을 만들고 다음을 넣습니다.

```js
const express = require('express')
const app = express()

app.get('/', (req, res) => {
  res.send('Hello, 이름!')
})

app.listen(3000)
```

### 4. 실행

```bash
node app.js
```

브라우저에서 http://localhost:3000을 엽니다.
"Hello, 이름!"이 보이면 성공입니다.

차이점이 보입니다: 결과의 이미지가 첫 단락에 있습니다, 분기와 선택지가 없습니다, 각 단계 끝에 확인할 신호가 있습니다.

학습자는 12분 안에 자기 이름이 브라우저에 뜨는 걸 봅니다.

템플릿

복사해서 시작점으로 쓸 수 있는 골격입니다.

# [결과물 이름]을 만들어봅니다

이 튜토리얼에서는 [결과물]을 만듭니다.
끝나면 [구체적인 결과물의 이미지]가 손에 남습니다.

소요 시간: 약 [N]분
필요한 것: [최소한의 전제]

## 1. 환경 준비

[최소한의 설치 명령]

확인:
```
[기대 출력]
```

## 2. 첫 동작 — [10분 안의 작은 성공]

[코드 또는 명령]

확인: [눈으로 볼 수 있는 신호]

## 3. [확장 단계 1] — [한 줄 설명]

[코드 또는 명령]

확인: [신호]

## 4. [확장 단계 2] — [한 줄 설명]

...

## 완성

축하합니다. [완성된 결과물 설명].

여기까지 따라오면서 [무엇을] 다뤘습니다.

### 다음으로

- [이 결과물을 발전시키는 방향]: [링크]
- [관련 개념을 더 알고 싶다면]: [Explanation으로 가는 링크]
- [실제 문제 해결법은]: [How-to로 가는 링크]

체크리스트

튜토리얼을 다 썼다고 생각될 때 짚어봅니다.

참고 자료

Procida, D. Diátaxis: Tutorials. https://diataxis.fr/tutorials/
Mozilla Developer Network. Express/Node introduction. https://developer.mozilla.org/en-US/docs/Learn/Server-side/Express_Nodejs
The Good Docs Project. Tutorial template. https://www.thegooddocsproject.dev/template/tutorial

다음 편 예고

ep.03 - 한 가지 목적을 해내는 절차, 하우투 가이드

다음 편은 하우투입니다. 튜토리얼과 가장 자주 혼동되지만 가장 다른 글. 독자가 이미 무엇을 하려는지를 알고 왔을 때, 어떻게 그를 가장 짧은 거리로 결과까지 데려갈 것인가. 전제·단계·검증이라는 단순한 골격이 왜 자주 무너지는지를 봅니다.