IT 직무 사전: ‘테크니컬 라이터’는 하루 종일 글만 쓰나요?

[요즘IT 직무 사전] IT업계의 숨은 직무 알아보기 #1

“IT 직군 하면 어떤 게 떠오르시나요?”

개발자, 기획자, 디자이너… 대부분의 사람들이 이 세 가지 직군을 먼저 떠올릴 텐데요. 그러나 IT업계에는 이 직군들 외에도 다양한 역할의 숨은 직무가 많습니다.

오늘은 그중에서도 ‘테크니컬 라이터(Technical Writer)’라는 직무를 조명해 보려고 합니다.

• 테크니컬 라이터는 정확히 어떤 일을 할까요?
• 개발자도 아니고, 기획자도 아닌데, IT업계에서 어떤 중요한 역할을 할까요?
• 테크니컬 라이터가 되려면 어떤 역량이 필요할까요?

이 궁금증들을 해결하기 위해 요즘IT에서 IT업계의 숨겨진 직무, 숨은 조력자들을 만나보기로 했습니다. 이름하여 ‘요즘IT 직무 사전’이죠. 그 첫 번째 주인공 토스 테크니컬 라이터 한주연 님과 함께 ‘테크니컬 라이터’라는 직무에 대해 알아가는 시간을 가져봤습니다.

• 한주연 테크니컬 라이터: 토스 테크니컬 라이터. 기술 문서를 쓰고, 조직의 지식 시스템을 만드는 일을 합니다. 사람들이 더 잘 배우고, 더 잘 일할 수 있도록 돕는 일에 관심이 있습니다.

‘테크니컬 라이터’는 실제로 어떤 일을 하나요?

Q. 아직 ‘테크니컬 라이터’라는 직무가 생소한 분들도 많을 것 같은데, 정확히 어떤 일을 하는지 소개해 주세요!

보통은 ‘개발자들이 보는 문서를 쓰는 사람’이라고 간단히 설명하곤 하는데요. 테크니컬 라이터(Technical Writer)라는 이름에서 알 수 있듯이 “기술적인 내용”을 “글로 쓰는” 사람이에요. 테크니컬 라이터가 하는 글쓰기를 ‘테크니컬 라이팅’이라고 부르는데요. 기술적인 내용을 정확하고 효과적으로 전달하는 글쓰기를 뜻합니다. 중요한 점은 이 글쓰기의 목표는 독자가 문제를 해결하고 목표를 이루도록 돕는 일이라는 거죠. 

이런 관점에서 보면 테크니컬 라이터는 단순히 문서를 쓰는 사람이 아니라, 개발자에게 전달되는 모든 ‘이해의 경로’를 설계하는 일에 더 가까워요. 텍스트로 된 문서뿐 아니라, 예제 코드, 샌드박스, 시각적 흐름도, 심지어는 문서가 언제 어떻게 업데이트되어야 하는지까지 모두 고민하죠.

Q. 그렇다면 테크니컬 라이터가 글쓰기를 넘어 꼭 고민해야 하는 부분은 무엇인가요?

도메인 용어나 지식을 충분히 다루는 것도 중요해요. 특히 외부에 오픈된 문서라면 비개발자들도 얼마든지 참고할 수 있거든요. 예를 들어, 단순히 어떤 API를 호출하는 방법에 대한 설명으로 끝내지 않고 어떤 도메인 지식 위에서 작동하는지도 함께 설명합니다. 왜냐하면 많은 개발자들이 새로운 제품이나 기술을 처음 접할 때는 그 분야나 흐름 자체가 생소하거든요. 결국 테크니컬 라이터의 가장 중요한 목표는 ‘독자가 문제를 해결하고 목표를 이루도록 돕는 것’이기 때문에 이런 방식으로 접근했어요.

Q. 일반적인 IT 직군(개발자, 기획자 등)과 비교했을 때, 테크니컬 라이터만의 가장 큰 차이점은 무엇인가요?

가장 큰 차이는 최종 사용자가 개발자라는 점이고, 결과물이 코드나 애플리케이션이 아니라 ‘문서’라는 점이에요. 저는 문서도 하나의 제품이라고 생각하는데요. 단순히 텍스트로 정보를 전달하는 데 그치지 않고, 개발자가 빠르게 이해하고 바로 활용할 수 있도록 돕는 기능을 모두 담고 있다는 점에서 그렇죠. 또 일종의 기술 제품 마케터 역할이기도 합니다. 개발자들은 문서를 보고, 이 기술이나 제품의 가치를 이해하고 도입하는 과정은 편리한지 등을 고려하거든요. 그래서 전문적인 내용을 다루지만, 쉽게 써야 한다는 과제를 늘 안고 있어요.

조금 다른 이야기지만, 문서를 바라보는 관점도 다른 것 같아요. IT업계에서는 문서를 종종 ‘추가적인 작업’이나 ‘귀찮은 일’로 보는 분위기도 없진 않은데요. 테크니컬 라이터는 그와 정반대 입장에서 역할을 한다는 생각이 들 때도 있어요. 테크니컬 라이터 입장에서 문서는 일이 더 빨라지고, 협업이 쉬워지고, 개발자가 더 많은 것에 집중할 수 있게 해주는 중요한 도구예요.

Q. 이 직무에 대해 사람들이 흔히 갖고 있는 편견이나 오해가 있다면요?

가장 흔한 오해는 테크니컬 라이터가 하루 종일 혼자 앉아 조용히 글만 쓸 것 같다는 이미지인 것 같아요. 실제로는 그 반대에 가깝죠. 예를 들어, 제품 문서를 만들려면 PO, 디자이너와 함께 어떻게 문서에 제품 가치를 녹이고 설명할지 이야기해요. 기본적으로 개발자들과는 항상 함께 이야기 나누면서 지식을 정리하고 구조화해야 하고요. 이렇게 매일 다양한 직군의 동료들과 협업하고 있어요.

또 다른 오해는 테크니컬 라이터가 기술과 글쓰기 둘 다 통달한 ‘만능형 전문가’여야 한다는 부담감인 것 같아요. 물론 기술 지식이나 글쓰기 역량은 중요하죠. 하지만 테크니컬 라이터가 세상의 모든 기술을 처음부터 잘 알 수는 없어요. 다만 매번 새롭게 다뤄야 하는 기술이나, 개념을 빠르게 습득하는 ‘학습 역량’이 더 중요한 것 같아요. 그 학습을 바탕으로 개발자를 도울 수 있어야 하고요. 그래서 개발자의 문제 해결 과정을 진심으로 궁금해하고 이해하려는 태도가 핵심이에요.

Q. 토스에서는 테크니컬 라이터가 구체적으로 어떤 역할을 하나요?

지난 3년간 토스페이먼츠에서 외부 개발자를 위한 개발자센터를 만들었고, 작년부터는 토스 프론트엔드 챕터에서 내부 팀원을 위한 지식 시스템을 만드는 일을 하고 있어요. 토스에서 테크니컬 라이터는 단순히 문서를 작성하는 것에 머무르지 않아요. 문서를 기반으로 사람들이 지식에 더 쉽게 접근하고, 실제 업무에 적용할 수 있도록 지식 시스템을 설계합니다.

예를 들어, 개발자가 문서를 일일이 찾지 않아도 사내 메신저에서 자연스럽게 질문하고 답을 받을 수 있도록 챗봇 ‘박씨’를 만들고 운영하거나, 기술 논의가 오간 대화를 자동으로 감지해 초안 문서를 생성해 주는 시스템을 설계해서 개발자와 함께 만들고 있어요. 또 코드 변경과 문서 변경이 함께 이뤄지도록 문서 자동화 도구도 만들고 있고요. 이렇게 문서를 단순히 ‘텍스트 결과물’로 보지 않고, 조직 안에서 지식의 기반으로 바라보면서 시스템 차원에서 접근하고 있습니다.

조직이 성장할수록 질문이 늘어나고, 커뮤니케이션 비용이 급증하잖아요. 이때 잘 설계된 문서는 팀 전체의 속도와 품질을 유지시켜 주는 핵심 구조가 됩니다. 이 인프라는 새로운 팀원의 온보딩 비용도 줄이고, 기존 구성원들의 지식수준도 비슷하게 유지해 주죠. 저는 이런 작업들을 챕터나 특정 팀을 넘어, 전사적인 지식 시스템으로 확장해 나가고자 합니다.

이외에도 프론트엔드 챕터에서는 외부에 오픈소스로 공개하는 도구나, 문서가 많은데요. 이렇게 외부용 문서도 함께 설계하고 리뷰해서, 외부 개발자들도 쉽게 이해하고 활용할 수 있도록 정제된 정보를 제공합니다. 개발자들 스스로도 이런 문서 작업을 잘할 수 있도록 교육 세션을 열거나, 테크니컬 라이팅 가이드를 배포하기도 했어요.

개발자도 ‘테크니컬 라이터’가 될 수 있을까?

Q. 주연 님은 개발자에서 테크니컬 라이터로 전향하셨는데, 어떤 계기가 있었나요?

제가 개발자로 일할 때 가장 큰 고민은 ‘학습’이었어요. 새로운 기술을 계속 따라가야 하고, 모르는 걸 빠르게 익혀야 하는데, 그게 쉽지만은 않더라고요. 이 학습 과정에서 문서를 많이 참고하게 되는데, 그때마다 참 이해하기 어렵게 설명되어 있다는 생각을 자주 했어요. 반대로 정말 잘 만들어진 문서를 보면 이해가 쏙쏙 되고 너무 재밌는 거예요. 코드와 결과물이 같이 보이거나, 인터렉티브한 방식으로 이해할 수 있게 도와주거나 하는 문서를 보면서 유용하다고 생각했고요. 

아무도 시키지 않았지만 스스로 문서를 만들어, 기술 조직 내 커뮤니케이션 비용을 줄이는 일도 재밌었어요. 원래도 교육이나 정보 전달에 관심이 많은 편이라 개발자로 일하면서 테크니컬 라이팅에도 자연스럽게 관심이 생겼던 것 같아요.

Q. 개발자와 테크니컬 라이터, 두 직무를 경험해 보셨는데 어떤 차이가 있나요?

막상 일을 시작해 보니까 테크니컬 라이터가 할 수 있는 일의 범위가 생각보다 훨씬 넓었어요. 개발자로 일할 때는 주니어기도 해서 제가 맡은 영역에 좀 더 집중했다면, 테크니컬 라이터가 되고 나서는, 제품 설계부터 개발자에게 문서로 전달되는 전체 흐름 속에서 일하게 됐죠.

예를 들어, API 문서를 만들 때 단순히 전달받은 내용을 정리하는 게 아니라, 실제로 API를 어떻게 설계할지부터 개발자들과 함께 고민했어요. 네이밍을 같이 정하고, OpenAPI 포맷에 맞춰 구조를 짜고, 사용자 입장에서 어떤 부분이 헷갈릴 수 있을지를 미리 짚으면서 문서를 같이 만들어 갔습니다. 이런 과정이 정말 재밌었고, API 결과물이나 문서의 완성도도 훨씬 높아졌어요. 

개발자로 일할 때도 내가 만든 결과물이 어떤 가치를 주는지를 계속 고민했는데, 지금은 그 방향이 더 명확해진 것 같아요. 개발자라는 명확한 타깃에 실질적인 도움을 주는 일이라는 점에서 테크니컬 라이터라는 역할이 저에게 훨씬 잘 맞는다고 느낍니다.

Q. 테크니컬 라이터로 직무를 변경하면서 어려웠던 부분도 있을까요?

테크니컬 라이터라는 직무를 처음 시작했을 때의 어려움은 두 가지였어요. 첫째는 제품이나 도메인에 대한 배경지식이 부족해서, 문서를 어떻게 설계해야 할지 감을 잡기 어려웠던 점입니다. 이 부분은 제품팀과 여러 번 만나 이야기를 나누고, 꾸준히 협업하면서 자연스럽게 해결됐어요.

둘째는 문서가 실제 개발자에게 얼마나 도움이 되고 있는지 확인이 어려웠다는 점이에요. 처음에는 사용자 피드백이나 실제 사용 데이터를 볼 수 없어서, 거의 직관에 의존해 문서를 작성해야 했어요. 이럴 때는 어떤 내용을 먼저 보여줄지, 어느 수준까지 설명해야 할지 결정할 근거가 없어서 막막했죠. 그래서 개발자들을 직접 만나 인터뷰하고, 사용성 테스트(UT)를 하면서 문서를 읽는 입장에서 어떻게 느끼는지 꾸준히 확인했어요. 또 문서 제품에 대한 지표 정의도 많은 도움이 됐어요. 문서 진입 후 개발자의 목표 달성과 관련된 지표가 개선되는지 점검하는 것이죠.

Q. 테크니컬 라이터로서 미리 알았다면 좋았을 점이 있다면요?

테크니컬 라이터가 가져야 할 전반적인 지향점이나 태도에 관해 이야기하고 싶은데요. 어떤 배경을 가지고 테크니컬 라이터가 되든, 사람들의 학습 방식이나 일하는 흐름을 면밀히 관찰하고, 그걸 돕는 데 관심이 있는지가 테크니컬 라이터로써 가장 중요한 부분이라고 생각합니다. 결국 문서를 만드는 일의 본질은 사람들의 학습과 업무를 돕는 거니까요. ‘기술 문서를 쓴다’라는 것보다 ‘지식이 효과적으로 전달되도록 만든다’라는 감각이 있어야 하고, 그걸 좋아해야 오래 할 수 있는 일인 것 같아요.

테크니컬 라이터가 되려면 어떤 경험이 필요할까?

Q. 테크니컬 라이터는 개발 경험이 있어야 할까요? 실제 현업에서는 개발 경험 여부가 얼마나 영향을 미치는지 궁금합니다.

개발 경험이 꼭 필수라고 말할 수는 없지만, 확실히 도움이 되는 건 맞아요. 기술 문서의 주요 사용자인 개발자가 어떤 상황에서 어떤 정보를 필요로 하는지 감을 잡는 게 중요한데, 이미 관련 경험이 있다면 문서의 방향이나 깊이를 정하는 데 유리합니다. 저는 프론트엔드 개발자로 일한 경험 덕분에, 프론트엔드 개발자들이 자주 겪는 문제나 모던 웹 개발에서 쓰는 도구들에 대한 기본적인 이해가 있었어요. 그래서 프론트엔드 개발자가 읽는 문서라면 어떤 내용을 설명해야 하고, 어디서 혼란이 생길 수 있는지 좀 더 자연스럽게 파악할 수 있었죠. 

하지만 개발자 출신이 아니어도 테크니컬 라이터는 충분히 할 수 있어요. 다만 설명하는 애플리케이션을 직접 실행해 보고, 자신이 쓴 설명대로 잘 작동하는지 확인할 수 있는 역량은 필요하다고 생각해요. 결국 ‘문서를 보고 개발자들이 실제로 구현할 수 있느냐’가 핵심이기 때문에, 개발자 입장에서 직접 실행하고 테스트해 볼 수 있어야 좋은 문서를 만들 수 있습니다.

Q. 비개발자가 테크니컬 라이터를 준비한다면 어떤 역량부터 갖추는 게 가장 효과적일까요? 기술 이해도를 높이는 방법이나, 반드시 알아야 할 기술 기초 지식 등을 추천해 주세요.

앞서 말씀드린 것처럼 개발자들이 어떤 환경에서 일하는지 직접 체험해 보는 게 정말 중요하다고 생각해요. 예를 들어, 단순히 개념을 외우는 것보다는, 간단한 예제 프로젝트를 따라 만들어보면서 실제 개발 흐름을 몸으로 익혀보는 게 훨씬 도움이 돼요.

예를 들면 문서에 나온 코드 예제를 따라 해보고, 예상대로 동작하지 않을 때 오류 메시지를 보고 해결하는 과정이 필요하죠. 이 과정에서 개발자들이 어떤 지점에서 막히는지 이해할 수 있어요. 또 Git이나 터미널 같은 개발자들이 매일 사용하는 기본 도구들, 혹은 ‘빌드’나 ‘배포’처럼 개발 흐름 속에서 자주 나오는 키워드들이 어떻게 돌아가는지 감을 잡는 것도 중요해요. 특정 분야나 개념을 완벽하게 이해하려는 목표보다는, 개발자가 해결해야 하는 문제를 체험해 본다는 느낌으로 접근하면 부담 없이 시작할 수 있을 거예요.

Q. 반대로 개발자가 테크니컬 라이터로 전향할 때는 어떤 부분에 신경 써야 할까요? 개발자 출신이 놓치기 쉬운 포인트가 있다면요?

개발자가 테크니컬 라이터로 전향할 때 가장 많이 놓치기 쉬운 부분은, 자신이 이미 알고 있는 내용을 무심코 전제로 삼고 글을 쓰는 점이에요. ‘이건 다 알겠지’, ‘이건 굳이 설명하지 않아도 되겠지’라고 생각하며 넘어가는 경우가 많지만, 실제로는 당연하다고 여겼던 부분에서 독자들이 막히기 쉬워요.

특히 어떤 기술이나 도구를 처음 접할 때는 전체 흐름을 먼저 잡아줘야 세부 내용을 잘 이해할 수 있어요. 이 과정을 생략하면 이후 설명이 아무리 자세해도, 독자 입장에서는 전체 그림이 잘 그려지지 않죠. 그래서 저는 항상 문서 초반에 주요 개념을 짚고 넘어가는 개요를 넣으려고 해요. 흐름도나 전체 과정을 조망할 수 있는 내용을 함께 담아서, 이 문서에서 무엇을 다루는지, 읽으면 무엇을 알 수 있는지, 전체 과정이 어떻게 진행되는지 먼저 보여줍니다. 이렇게 하면 독자들이 문서를 읽는 내내 스스로 어디쯤 와 있는지 인식할 수 있어요.

Q. 실제 업무를 하면서 가장 많이 했던 실수는 무엇이고, 이를 해결하는 주연 님만의 노하우가 있나요?

제가 문서를 쓸 때 가장 중요하게 생각하는 건 두 가지예요. 하나는 코드고, 다른 하나는 용어와 개념의 일관성이에요. 코드를 먼저 짚은 이유는 일단 개발자는 결국 코드를 먼저 보기 때문이에요. 아무리 설명이 잘 되어 있어도 코드가 없으면, 머릿속에 잘 안 들어오는 경우도 많더라고요. 그래서 문서를 쓸 때는 예제 코드를 빠르게 보여주고, 코드를 중심으로 설명을 풀어가요. 물론 예제만으로 이해가 안 될 때가 많아서 설명도 당연히 함께 준비해야 하죠. 예제를 이해하지 못했을 때 그 내용을 다시 잡아주는 안전망 역할을 하도록요.

또 하나는 용어입니다. 기술 문서는 원래도 정보량이 많은데, 한 문서에서 같은 개념을 조금씩 다르게 표현하면 독자 입장에서는 혼란이 생겨요. 그래서 한 번 정한 용어는 최대한 일관되게 사용하고, 또 도메인과 관련된 개념도 처음부터 명확하게 정의하려고 해요.

예를 들어, 특정 단어가 지금 다루는 도메인에서 어떤 의미로 쓰이는지 처음부터 분명히 짚어주면, 이후 다른 설명들도 자연스럽게 이어지더라고요. 이 외에도 문서를 작성할 때 참고하는 원칙이나 패턴은 따로 테크니컬 라이팅 가이드로 정리해 두고, 실무에서 함께 문서화하는 분들과 공유하며 계속 업데이트하고 있습니다.

테크니컬 라이터의 미래는?

Q. 앞으로 테크니컬 라이터의 역할은 어떻게 변화할 것으로 생각하시나요? AI로 인한 변화도 있을까요?

앞으로 테크니컬 라이터라는 역할은 점점 더 “글을 쓰는 사람”에서 “지식 시스템을 설계하는 사람”으로 바뀌게 될 것 같아요. 저도 단순히 문서를 작성하는 데 그치지 않고, 문서를 더 잘 만들고 잘 전달되도록 돕는 시스템 자체를 설계하고 운영하고 있어요.

이때 문서가 외부 고객을 위한 것인지, 내부 조직을 위한 것인지에 따라 중요하게 고려해야 할 포인트가 달라지는데요. 외부 문서는 사용자들이 우리 제품을 빠르게 이해하고 도입할 수 있도록 돕는 것이 핵심입니다. 단순히 정보를 나열하는 걸 넘어, 하나의 온보딩 경로이자 체험의 일부라고 생각하고 설계해야 하죠. 실제로 이 온보딩 경험이 도입률과 전환율에 큰 영향을 미치기 때문에, 사용자가 기술을 쉽게 이해하고 직접 써볼 수 있도록 문서를 구성하는 게 중요합니다.

최근에는 AI의 도움으로 비개발자도 제품을 직접 만들 수 있는 흐름이 강해지고 있어서, 문서의 타깃을 기존 개발자 중심에서 더 넓게 바라볼 필요가 있어요. 이제는 사람들이 AI에 우리 제품의 문서를 학습시켜서 같이 코딩할 수 있도록 도와주는 기능을 고려해야 할 것 같아요.

내부 문서는 좀 다른데요. 각 조직만의 도메인 용어, 맥락, 팀 간 협업 구조를 잘 반영해야 하고, 어떤 지식이 어디로 흘러야 할지 체계적으로 설계하는 일이 중요합니다. 예를 들어, 개발자·DA·PO 등 실제로 개념을 다루는 사람들과 의미를 함께 정의하고 정제하는 과정이 반드시 필요하죠. 내부 조직의 맥락을 이해해야 해서, 이 부분은 AI가 쉽게 대체하기 어려워 보여요.

외부 문서와 내부 문서 모두에서 점점 더 중요해지는 부분은, 문서가 AI가 활용할 데이터라는 관점이 아닐까 싶어요. 그래서 구조화된 문서 포맷(Markdown, OpenAPI, JSON Schema 등)이나 프롬프트에 적합한 문장 구성이 점점 더 필요해질 것 같아요. 궁극적으로는 AI가 문서를 바탕으로 사용자의 목적을 이해하고, 알맞은 코드를 생성하거나 설정을 구성해 주는 방향으로 발전하겠죠.

흥미로운 점은 결국 사람에게 읽기 쉽게 쓰인 문서가 AI도 학습하기 좋은 문서라는 거예요. 문장의 구조가 명확하고, 용어가 일관되고, 흐름이 잘 잡힌 문서일수록 AI가 더 정확한 답을 내릴 수 있어요. 이런 문서는 기본적으로 사람이 읽기에도 수월하죠. 그래서 앞으로 AI가 문서의 활용도를 높여줄 수 있는 도구로 발전할수록, 좋은 문서를 만드는 일의 중요성도 더 커질 거라고 생각합니다.

Q. 마지막으로 테크니컬 라이터를 꿈꾸는 분들에게 응원의 한 마디 부탁드립니다.

테크니컬 라이터에게 가장 중요한 건 고객인 개발자 혹은 그 외에도 학습이 필요하거나, 정보를 찾는 모든 사람들의 학습을 돕고 싶은 마음이라고 생각해요. 스스로에게 이런 마음이 있는지 천천히 고민해 보고, 그 답을 하나씩 찾아가셨으면 좋겠습니다.

지금까지 토스 테크니컬 라이터 한주연 님과 함께, 테크니컬 라이터라는 직무가 어떤 일을 하고, 어떻게 준비하면 좋은지 자세히 알아봤습니다. 테크니컬 라이터는 단순히 기술 문서를 작성하는 일을 넘어, 개발자와 사용자 사이에서 복잡한 기술을 쉽게 이해할 수 있도록 돕는 소통의 가교 역할을 하고 있다는 점이 특히 인상 깊었는데요.

테크니컬 라이터에 관심이 있다면, 이번 인터뷰를 통해 기술 이해력, 글쓰기 역량, 효과적인 커뮤니케이션과 같은 핵심 역량을 차근차근 준비해 보셔도 좋겠습니다. 현재 토스에서 ‘테크니컬 라이터’ 직군을 채용 중이라고 합니다. 관심 있는 분들은 [채용 공고]를 확인해 보세요.

앞으로도 요즘IT 직무 사전을 통해 업계의 숨은 직무를 소개할게요. 궁금했던 직무가 있다면 댓글로 알려주세요!

©️요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.