오류 문구를 검색창에 붙여 넣으면 수많은 블로그 글과 질문 게시판이 쏟아집니다. 그중 무엇을 믿어야 할까요? 이 레터의 답은 간단합니다. 검색 결과를 읽기 전에 공식 문서를 먼저 엽니다. 공식 문서는 지루해 보여도 지금 버전 기준으로 가장 정확한 설명을 담고 있습니다.
공식 문서가 먼저인 이유
프로그래밍 언어와 라이브러리는 생각보다 자주 바뀝니다. 몇 해 전에 쓰인 블로그 글의 코드가 지금은 경고를 내거나 아예 동작하지 않는 일이 흔합니다. 공식 문서는 바뀐 내용을 가장 먼저 반영하고, 더 이상 쓰지 않는 기능에는 표시를 붙입니다. 같은 문제를 다룬 글이 여러 개일 때 기준점이 되어 주는 셈입니다.
웹 개발이라면 MDN Web Docs가 대표적입니다. HTML 요소, CSS 속성, 자바스크립트 기능마다 설명과 예제, 브라우저 지원 표가 있습니다. 구글이 운영하는 web.dev는 성능과 접근성 같은 주제를 깊게 다루고, 마이크로소프트의 Microsoft Learn은 자사 도구와 클라우드 문서를 한국어로도 제공합니다.
문서마다 쓰임이 다릅니다
| 문서 종류 | 언제 여나 | 예 |
|---|---|---|
| 레퍼런스 | 함수나 속성의 정확한 사용법이 궁금할 때 | MDN Web Docs의 속성 설명 |
| 가이드·튜토리얼 | 처음 배우거나 흐름을 익힐 때 | Android 개발자, Apple Developer의 시작 안내 |
| 릴리스 노트 | 버전을 올린 뒤 달라진 점을 볼 때 | GitHub 저장소의 Releases |
| 기술 블로그 | 실제 서비스에서 겪은 사례가 궁금할 때 | 네이버 D2, 토스 테크 |
레퍼런스와 가이드는 같은 사이트 안에 함께 있는 경우가 많습니다. 처음에는 가이드로 큰 그림을 보고, 막히는 지점에서 레퍼런스를 찾아 읽는 순서가 편합니다.
검색 결과를 걸러 내는 세 가지 기준
- 글이 쓰인 날짜와 다룬 버전이 적혀 있는지 봅니다. 둘 다 없다면 공식 문서와 대조합니다.
- 코드를 복사하기 전에 그 코드가 무엇을 하는지 한 줄씩 이해했는지 스스로 묻습니다.
- 공식 문서를 통째로 옮긴 사이트보다 원문 문서로 가서 읽습니다.
질문 게시판인 Stack Overflow는 여전히 쓸모가 큽니다. 다만 채택된 답변이 오래전 것이라면 아래쪽의 최근 답변을 함께 읽고, 그 답변이 가리키는 공식 문서 링크를 따라가 보는 습관을 들이면 좋습니다.
국내 기술 블로그를 읽는 법
카카오 기술 블로그, 우아한형제들 기술블로그 같은 국내 기업 블로그는 실제 서비스를 운영하며 겪은 문제를 풀어 씁니다. 같은 기술이라도 규모와 환경에 따라 선택이 달라진다는 것을 배울 수 있어 좋습니다. 한편으로는 그 회사의 상황을 전제로 한 글이라는 점을 기억하고, 내 프로젝트에 그대로 옮기기 전에 공식 문서로 다시 확인합니다.
개발 도구를 새로 설치해야 한다면 문서보다 먼저 공식 설치처를 확인합니다. 검색 광고 속 가짜 다운로드를 피하는 방법은 개발 도구 공식 설치처 확인하기에 정리했습니다. 공식 문서와 저장소, 기술 블로그 주소는 웹·IT 우편함에 모아 두었습니다.
문서를 읽는 작은 요령
공식 문서는 처음부터 끝까지 읽기보다 필요한 곳을 찾아 읽는 책에 가깝습니다. 문서 안의 검색창을 쓰거나, 브라우저의 페이지 내 찾기로 함수 이름을 찾으면 빠릅니다. 예제 코드는 그대로 복사하기 전에 작은 파일에 옮겨 직접 실행해 보고, 값을 하나씩 바꿔 가며 결과가 어떻게 달라지는지 보면 이해가 훨씬 깊어집니다.
문서 위쪽이나 옆쪽에 있는 버전 선택 메뉴도 확인합니다. 내가 쓰는 버전과 문서의 버전이 다르면 설명이 맞지 않을 수 있습니다. 브라우저 지원 표가 있는 문서라면 내가 지원해야 하는 브라우저에서 그 기능을 쓸 수 있는지도 함께 봅니다.
- 문서 안 검색창으로 필요한 항목을 바로 찾습니다.
- 예제는 작은 파일에서 직접 실행해 봅니다.
- 문서의 버전과 내 환경의 버전을 맞춥니다.
- 자주 보는 문서 페이지는 북마크 폴더로 묶습니다.
문서에서 찾은 내용은 짧게라도 내 말로 정리해 두면 다음에 같은 문제를 만났을 때 훨씬 빨리 해결할 수 있습니다. 정리할 때는 원문 문서의 주소를 함께 적어 두세요. 나중에 문서가 갱신되었는지 확인할 때 바로 찾아갈 수 있습니다.
문서를 읽다 오류나 오타를 발견했다면 문서 아래쪽의 수정 제안 링크로 알릴 수도 있습니다. MDN처럼 공개 저장소로 문서를 관리하는 곳은 누구나 고침을 제안할 수 있어, 읽는 사람에서 함께 만드는 사람으로 한 걸음 나아가는 계기가 됩니다.
레터 끝 질문
영어 문서가 어려우면 어떻게 하나요?
MDN과 Microsoft Learn처럼 한국어 번역을 제공하는 문서가 있습니다. 번역이 원문보다 늦게 갱신될 수 있으니, 중요한 부분은 언어를 영어로 바꿔 최신 내용과 비교해 보세요.
공식 문서와 블로그 내용이 다르면 무엇을 따르나요?
대개 공식 문서를 따릅니다. 블로그가 더 최신 내용을 다룬다면 그 블로그가 근거로 든 릴리스 노트나 이슈를 찾아 확인합니다.
기술 블로그 글은 어디서 모아 보나요?
각 회사 기술 블로그를 북마크하거나 RSS 구독 기능을 쓰면 편합니다. 주소는 주소조아 웹·IT 우편함에 있습니다.
