테크니컬 라이팅 원칙 (빅테크)

빅테크(Google·Netflix·Uber·토스·LINE)의 테크니컬 라이터들이 쓰는 글쓰기 프레임워크와 규칙 모음.

언제 찾게 되는가: 블로그 글(devlog)이나 위키 페이지를 쓰다가 “구조를 어떻게 잡지”, “이 문장이 왜 어색하지” 싶을 때. /devlog 퇴고 패스와 wiki Reference 계약의 원전이 여기다.

핵심 답: 글 유형을 먼저 정하고(Diátaxis), 독자를 특정하고, 문단 첫 문장에 결론을 놓고(Google), 버린 대안과 감수한 비용을 쓰고(Netflix), 잡초 단어를 지운다(토스).

📄 문서 기반 (2026-07 웹 리서치). 각 원칙의 출처는 섹션별 링크 참조.

프레임워크 4가지

1. Diátaxis — 문서 유형의 계약

문서를 2축(실천↔이론 / 학습↔적용)으로 나눠 4유형으로 분류한다. 한 글에서 유형을 섞으면 모든 독자를 실망시킨다.

유형	성격	이 위키 체계에서
Tutorial	학습 + 실천, 손잡고 이끄는 수업	(해당 없음)
How-to	적용 + 실천, 문제 해결 절차	wiki 일부 (해결 전략 섹션)
Reference	적용 + 이론, 사실을 구조적으로	wiki `content/`
Explanation	학습 + 이론, 서사·트레이드오프 허용	devlog `posts/`

출처: diataxis.fr

2. Google Tech Writing — 문장·문단 린트

Google의 사내 교육과정(공개됨). 핵심 규칙:

문단 첫 문장 = 그 문단의 결론 (topic sentence). 첫 문장만 이어 읽어도 논지가 성립해야 한다.
한 문장 = 한 아이디어. 긴 문장은 리스트로.
능동태 우선, 구체적 동사, “there is/~가 있다” 제거.
새 용어는 첫 등장 시 정의, 이후 동의어 혼용 금지. 모호한 “이것/그것” 금지.
문서 서두에 범위(scope)·독자(audience)·핵심(key points) 선언.

출처: developers.google.com/tech-writing (One 요약 , Two 요약 )

3. Netflix TechBlog — 서사 패턴

대표 글들의 실측 구조:


비즈니스 컨텍스트로 개막 (기술명으로 시작하지 않음)
→ 구체적 시나리오 1개로 문제 제시
→ 기존 접근의 한계 (비난 없이 트레이드오프로 서술)
→ 대안 비교와 선택 근거
→ 중간 피벗·실패 솔직 공개 ("운영 오버헤드는 늘었지만 감수했다")
→ 결과는 수치로 ("초당 100만 메시지")
→ 회고 + 열린 문제

출처: netflixtechblog.com (예: Real-Time Distributed Graph Part 1 )

PowerPoint 금지 후 도입된 서사 메모 문화. 철학: 엉성한 논리는 슬라이드에서는 숨지만 완전한 문장·문단에서는 드러난다. 퇴고 시 “문단 간 논리 비약이 있는가”, “결정의 근거가 데이터인가 수사인가”를 자문한다.

출처: sixpagermemo.com

라이터 직군에서 배울 태도

Uber: 라이터가 직접 기술을 핸즈온으로 학습·검증한 뒤 쓴다. → 검증 안 한 내용은 미검증이라고 표기.
토스페이먼츠: “문서로 설명하기 어려운 API 스펙 = 코드 스멜” — 설명이 꼬이면 설계를 의심한다. 라이팅 가이드를 오픈소스로 공개: technical-writing.dev (① 문서 유형 정하기 ② 정보 구조 만들기 ③ 문장 다듬기).
토스 8가지 라이팅 원칙 중 전이 가능한 것: 잡초 제거(없어도 되는 단어 삭제), 빈 문장 제거(제목 반복 금지), 핵심 메시지 집중. 출처: toss.tech/article/8-writing-principles-of-toss
LINE/카카오: 테크니컬 라이팅 = “특정 독자에게 특정 목적으로 특정 정보를 전달하는 글쓰기”. 목표는 3C — Clear(명확), Concise(간결), Consistent(일관). 출처: LINE 인터뷰
Gergely Orosz: 잘된 글은 집계(aggregation)가 아니라 1차 경험과 원본 리서치에서 나온다. 일반론 문단이 3개 연속이면 글 방향을 의심하라.

이 위키 체계에 반영된 곳

devlog 스킬 (~/.claude/skills/devlog/SKILL.md) — TL;DR·서사형 소제목·독자 선언·3패스 퇴고(논리→잡초→약속 검증)
wiki 스키마 (CLAUDE.md의 “Reference 계약”) — 상단 3요소(정의/언제/핵심 답), 검증 표기, 탈선 감지
TIL — 의도적으로 한 줄 테이블 유지 (로그는 로그답게, Diátaxis 유형 혼합 금지의 적용)

AI 도구 생태계의 가속과 개발자의 자세