개발자와 공식 문서 사이의 어색한 거리감

개발자와 공식 문서 사이엔 늘 어색한 거리감이 있다

“문서를 못 알아보는 건 내가 실력이 없어서일까?” 나는 꽤 오래 동안 이렇게 믿고 살았습니다.

1. “나만 이해 못 하는 것 같았다”

프레임워크, 라이브러리, REST API, 클라우드 서비스… 이제 웬만한 건 다 공식 문서가 잘 되어 있죠. 문제는… 그걸 내가 잘 이해 못 한다는 거죠.

초보 때는 이렇게 생각했어요.

“아… 내가 아직 실력이 부족해서 그렇겠지. 좀 더 공부하면, 언젠간 이 문서도 술술 읽히겠지…”

그래서 열심히 읽어 봅니다. 그런데:

원리는 잘 모르겠고
어디까지가 개념이고 어디서부터가 실사용 예제인지 헷갈리고
분명 내용을 읽었는데, 막상 코드 짜려면 손이 안 움직이고
문서 양은 또 왜 이렇게 많은지…

지금은 적어도 “초보” 라는 소리는 듣지 않을 정도의 개발자가 되었다고 생각해요. 그래도 여전히 새로운 라이브러리 문서를 보면, 마음속에서 이런 소리가 납니다.

“와… 또 시작이네…”

실력 부족 탓만은 아니라는 걸, 이제는 압니다.

2. 문서는 보통 “만든 사람의 시선”으로 쓰여 있다

문서가 어려운 가장 큰 이유는, 대부분의 공식 문서가 “만든 사람의 머릿속 구조”를 기준으로 쓰여 있기 때문인 것 같아요.

그 사람은 이미
내부 구조를 알고 있고
왜 이런 설계를 했는지 알고 있고
어떤 제약이 있는지도 알고 있고
이 함수가 어디서 어떻게 호출되는지도 알고 있습니다.
그러니까 문서에는 주로 이런 것들이 적힙니다.
이 메서드는 이런 파라미터를 받고
이 타입을 반환하고
이 경우에는 예외를 던지고
이걸로 이런 걸 할 수 있다…

문제는, 우리는 그 프로그램을 만든 사람이 아니라는 거죠.

우리가 궁금한 건 보통 이런 것들입니다.

“이걸 어디서부터 시작해야 하지?”
“내가 지금 겪는 이 문제를 해결하려면 문서의 어느 부분을 보면 되지?”
“이 옵션이 실제로는 어떤 상황에서 필요한 거지?”
“이 코드 한 줄이 실제로 언제 호출되는 거지?”

하지만 문서는 이렇게 말합니다.

“이 옵션은 foo 라는 동작과 bar 라는 전략을 사용하여 baz 를 수행합니다.”

…이쯤 되면 그냥 예제를 먼저 돌려보고 싶어지죠.

3. “내 문서도 결국 남에겐 어렵다”

웃긴 건, 나도 제가 만든 API나 라이브러리에 대해 문서를 쓰잖아요. 그럼 또 똑같이 “만든 사람의 시선”으로 쓰게 됩니다.

“이 함수는 이런 기능을 하고…”
“이 엔드포인트는 이런 인자를 받고…”
“이런 형태의 JSON을 반환하고…”
“성공/실패 시 응답은 이렇고…”

그리고 생각하죠.

“이 정도면 꽤 친절한 문서 아닌가?”

그런데 팀원들 반응은 대충 이렇습니다.

“일단 구두로 한 번만 설명해주면 안 돼요?”
“문서가 있긴 한데… 그냥 물어보는 게 더 빠를 것 같아서요.”

더 웃긴 건, 내가 예전에 작성한 문서를 내가 못 알아볼 때도 있습니다.

오래전에 만든 API를 다시 쓰려고 예전 문서를 열어보면:

“어… 이거 내가 쓴 거 맞지? 왜 이렇게 설명을 이상하게 해놨지…?”

그때 깨달았어요.

문서를 썼다고 해서, 그게 곧 “잘 이해되는 문서”라는 뜻은 아니다.
내가 잘 안 읽히는 공식 문서를 욕할 자격이… 사실은 별로 없다. 😅

4. 공식 문서가 원래 “처음엔 안 읽히는” 게 정상이다

프로젝트마다 꼭 사용하는 라이브러리나 패키지 하나쯤 있잖아요. 그건 브라우저에 탭 고정해 놓고, 일하면서 계속 열어보는 그런 문서들.

그런데 신기한 게 있습니다.

처음 읽을 때는
“도대체 무슨 소리를 하는 거야…” 싶던 문장이
프로젝트 막바지쯤 다시 읽으면
“아, 이 말이 그 말이었구나…” 하고 이해가 됩니다.

그리고 자주 이런 생각을 합니다.

“아니, 이게 여기에 이렇게 적혀 있었네? 내가 예전에 분명 읽었는데, 그땐 이게 그 뜻인지 몰랐네…”

이게 왜 그럴까요?

문서 내용을 이해하려면, 어느 정도 써 본 경험과 맥락이 필요하고
그런데 그 경험을 쌓으려면 일단 대충이라도 문서를 보고 뭔가를 만들어 봐야 합니다.

즉, 문서를 이해하기 위해서 문서를 이해한 상태가 필요한 이상한 순환 구조에 빠지기 쉬운 거죠.

그래서 저는 이제 이렇게 생각합니다.

“공식 문서는 한 번에 이해하는 문서가 아니다. 몇 번 프로젝트 피를 보면서 다시 볼 때 비로소 읽히는 문서다.”

그러니까, 처음에 안 읽히는 게 정상입니다. 당신이 부족해서가 아니라, 원래 그런 구조인 겁니다.

5. 비영어권 개발자는 난이도 +2

여기에 우리는 비영어권 개발자라는 핸디캡까지 있습니다.

영어 문장 자체는 읽을 수 있어요.
기술 용어도 이제는 꽤 익숙합니다.
책도 좋아하고, 글 읽는 것도 좋아해서 “독해력”이 부족하다고 느껴지지도 않습니다.

근데도 공식 문서를 읽으면 이상하게 뇌가 더 빨리 피곤해지는 느낌이 듭니다.

이건 실력이 부족해서가 아니라:

영어라는 언어 자체에 지속적으로 “인지 비용”이 들어가고
거기에
새로운 개념
생소한 API 설계
추상적인 예제 코드 가 한꺼번에 밀려 들어오기 때문입니다.

즉, 남들보다 같은 내용을 이해하는 데 에너지 소모가 더 큰 게임을 하고 있는 거죠. 그럼 당연히 더 지치고, 더 어렵게 느껴질 수밖에 없습니다.

그래서 “왜 난 이렇게 공식 문서를 읽는 게 힘들지…” 라는 생각이 들 때, 이렇게 스스로에게 말해도 된다고 생각합니다.

“난 이미 핸디캡을 안고 열심히 달리고 있는 중이다.”

6. 그래도… 우리에겐 몇 가지 생존 스킬이 있다

위로만 하고 끝내긴 뭐하니, 제가 쓰면서 터득한 문서 생존 요령 몇 가지를 덧붙여볼게요.

6-1. “처음부터 끝까지 읽는다”는 욕심을 버리기

공식 문서는 보통 “참고서 + 사전” 같은 느낌으로 만들어져 있습니다.
입문서처럼 “첫 페이지부터 끝까지 읽으면 이해되는 구조”가 아닙니다.

그래서 저는:

“Getting Started / Quickstart / Tutorial”까지만 대충 보고
나머지는 그냥
검색용
문제 생겼을 때 뒤지는 용도 로 생각합니다.

6-2. 예제로 먼저 이해하고, 설명은 나중에 읽기

코드 한 줄 짜보고
에러 한 번 맞아보고
그 에러 메시지를 검색해서 다시 문서를 봅니다.

그러면 문장이 갑자기 이렇게 바뀌어 보입니다.

처음 읽을 때:

“이게 무슨 말인지 모르겠다…” * 몇 번 삽질 후에 다시 읽을 때:

“아 이거 그때 내가 당한 그 오류 얘기하는 거였네…”

실패 경험이 생긴 뒤에 읽으면 문서가 이야기처럼 읽히는 순간이 옵니다.

6-3. “내 언어로 메모하기”

공식 문서는 어쩔 수 없이 그들의 언어로 써 있습니다. 그래서 저는 자주 이런 메모를 남깁니다.

“이 옵션 true로 하면, 사실상 XXX 모드라고 생각하면 됨”
“이 함수는 ‘X를 만들어 주는 공장’ 정도 느낌”
“이 부분은 무조건 이렇게 외워서 쓰자. 깊게 이해는 나중에…”

나중에 내가 다시 볼 “나만의 문서”를 만들면 공식 문서랑 세트를 이뤄서 훨씬 든든해집니다. (물론 가끔 그 메모조차 “이게 뭐지?”가 될 때도 있지만요…)

7. 당신이 부족해서가 아니다

이 글을 여기까지 읽었다면, 아마 당신도 공식 문서 앞에서 한숨을 쉬어본 경험이 있을 겁니다.

여러 번 읽어도 이해가 안 되는 문장
분명 어제 봤는데 오늘 다시 찾아야 하는 섹션
문제를 해결하고 나서야 비로소 보이는 문장들

그럴 때마다 꼭 기억했으면 합니다.

당신만 그런 게 아닙니다.
지금도 잘하는 개발자들 대부분이 똑같이 헤매고 있습니다.
심지어 그 라이브러리를 매일 쓰는 사람들도 공식 문서보다 Stack Overflow나 GitHub 이슈를 더 자주 검색합니다.

공식 문서는 원래 어렵게 쓰여 있습니다. 그리고 그건 당신의 잘못이 아닙니다.

우리는 그냥,

이해 안 되면 다시 읽고
그래도 모르겠으면 코드부터 써보고
실패하면 다시 문서를 펼쳐보고
그러다 어느 날

“아, 그래서 이 사람이 이 문장을 이렇게 쓴 거구나…” 하고 깨닫는 과정을 반복할 뿐입니다.

그게 개발자로 산다는 것의 한 부분이 아닐까 싶습니다.

그러니까, 오늘도 문서 앞에서 좌절하고 있는 누군가에게 이렇게 말해주고 싶어요.

“당신은 잘못하고 있는 게 아니에요. 그냥, 개발자 구간을 정상 속도로 지나가는 중입니다.”

우리 모두 여전히 문서 앞에서 멍해지고, 탭 수십 개를 열어두고, 어제 보던 페이지를 오늘 또 찾으며 개발하고 있습니다. 그럼에도 프로젝트는 어떻게든 굴러가고, 우리는 또 한 줄씩 코드를 더 배워갑니다. 🙂