"삽질 끝에 겨우 알아냈다면 바로 글을 써라" 어느 개발자의 조언

요약 새로운 기술이나 도구를 배울 때 우리는 종종 답을 찾기 어려운 질문에 부딪힙니다. 예컨대 '왜 똑같은 일을 하는 API가 두 개나 있을까?', '예제 코드와 똑같이 작성했는데 왜 동작하지 않을까?' 같은 의문들입니다. 시간이 흘러 소스코드를 파헤치고 프로젝트 구조를 이해하며 결국 '전문가'가 되고 나면, 그 모든 해답이 너무나 당연하게 느껴지기 마련입니다. 하지만 필자는 바로 이 '초심자에서 전문가로 넘어가는 과정'에 대한 기록이 생태계에 결정적으로 부족하다고 지적합니다. 최근 마인크래프트 모딩(KubeJS)을 하며 겪은 경험이 대표적입니다. 특정 아이템 태그를 추가하는 짧은 자바스크립트 클로저 코드를 보며 필자는 'ServerEvents가 정확히 무엇이고 왜 클로저 안에서 실행되는지', '플레이어 행동과 무관한데 왜 이벤트라 부르는지' 의문을 품었습니다. 결국 KubeJS 문서와 코드, 연동된 모드 로더 NeoForge의 문서와 내부 코드, 믹스인(mixin) 패치 구조까지 직접 파고든 끝에야 이 구조가 서버 시작 시 동기적으로 실행되는 라이프사이클 이벤트임을 이해할 수 있었습니다. 필자는 대다수 기술 문서가 '초보자를 위한 5세 수준의 극단적 비유'이거나 '전문가만을 위한 불친절한 요약' 양극단에 머물러 있다고 꼬집습니다. HTTPS를 배울 때 비대칭 암호화나 디피-헬먼 키 교환으로 넘어가는 연결 고리를 모르면 헤매는 것처럼, 초심자가 중급자로 도약하는 징검다리 문서가 턱없이 부족하다는 것입니다. 전문가가 되고 나면 초심자 시절에 어떤 검색어로 헤맸는지, 무엇을 몰라 고통받았는지 금세 잊어버립니다. 따라서 며칠씩 삽질해 겨우 답을 찾았거나 심지어 실패했던 과정까지도, 기억이 생생한 '해결 직후'에 블로그나 SNS에 기록으로 남겨야 한다고 필자는 호소합니다. 아주 사소한 결론이라도 누군가에게는 그 지점까지 도달하기 위한 유일한 이정표가 되며, 오픈소스 메인테이너에게도 문서의 빈틈을 메울 수 있는 소중한 피드백이 되기 때문입니다.