훌륭한 기술 문서, 좋은 테크니컬 라이팅이란 뭘까?

훌륭한 기술 문서, 좋은 테크니컬 라이팅이란 뭘까? 이 주제에 대해 오랫동안 고민해왔는데, 최근 새로운 생각이 떠올라 현재의 생각을 정리해보려 한다.

라이터에게 라이팅이 중요해지지 않는다​면

테크니컬 라이터는 문서를 쓰는(writing) 것 외에도 다양한 일을 한다. 지난 3년 정도 그런 다양한 일을 한 뒤, 특히 AI라는 큰 변화를 겪으며 자연스럽게 테크니컬 라이터에게 '쓰는 일'이 이제 덜 중요하다고 느끼고 있다. 테크니컬 라이터에게 쓰는 일이 덜 중요하다니. 모순된 말 같지만 주요 사용자인 개발자가 정보를 얻고, 문서를 읽고 쓰는 경험이 바뀐다면 고민하는 부분도 바뀔 수 있다고 생각한다. 테크니컬 라이터에게 더 중요해진 일은 개발자에게 정말로 필요한 경험이 무엇인지를 파악하는 능력이다. 개발자들의 개발 환경은 계속해서 변하고 있기 때문이다.

그동안에도 이런 '개발자 경험 중심'이라는 관점을 어렴풋이 가지고 있긴 했지만 그 관점을 바탕으로 한 고민은 주로 '문서 경험을 어떻게 좋게 만들까', 그리고 '그 좋음을 어떻게 측정할까'에 집중되어 있었다. 하지만 요즘에는 단순히 하던 대로 작업하고, 그걸 어떻게 측정할지 고민하는 대신 더 앞단계에서 혹은 좀 더 넓은 관점에서 개발자의 경험을 관찰하고 개선하는 데에 관심이 생긴다. 즉, 문서가 작성된 후의 사용성보다 문서를 쓰고 사용하는 개발자들이 겪는 문제와 필요를 먼저 이해하는 방향으로 접근하고 있다.

'문서를 기반으로 한 업무 방식'의 재정의

이런 변화는 최근 회사 내 새로운 팀에 합류하면서 시작됐다. 처음 합류를 결정했을 때는 팀 내에 있는 지식을 전반적으로 문서화 하고 싶다는 이야기를 들었다. 그래서 그냥 팀 내의 지식을 모으고, 잘 쓰면 되는 것으로 꽤 단순하게 생각했다. 그런데 막상 합류하고 자세히 들어보니 80명 정도 규모의 팀에서 '문서를 기반으로 한 업무 방식을 정착시키고 싶다'는 목표가 있었다. 이렇게 메타적인 목표는 성과 측정이나 업무 방향 설정이 수월하지 않아 약간 걱정이 됐다. 또, 회사의 문화가 문서화를 지양하는 편이라 마치 1:100의 싸움을 혼자서 시작하는 것처럼 느껴져 지레 겁도 났다. 하지만 그동안 일을 하면서 해 온 고민을 잘 녹여볼 수 있는 기회라는 생각도 들었다. 지금까지 내가 테크니컬 라이터로서 가장 중요하다고 생각한 일은 개발자의 더 좋은 일 경험, 학습 경험에 문서가 어떻게 기여할 수 있는가를 고민하는 것이었기 때문이다. 그걸 조직 단위에서 시도할 수 있고 함께 좋은 방법을 고민해 볼 수 있는 사람들이 있어 서서히 의욕이 났다.

그런데, '문서를 기반으로 한 업무 방식을 정착시키고 싶다'는 목표를 더 깊이 들여다보면 거기에는 다양한 맥락이 섞여 있다.

• 구두로 전파되는 지식과 그로 인해 생기는 지식의 편차를 줄이고 싶다는 지식/학습의 민주화 관점
• 파편화되는 정보를 한 곳에 모으고 주기적으로 신선하게 업데이트하고 싶다는 조직의 효율적인 정보 관리 관점
• 몇몇 사람에게 기대어 업무를 해야 하는 상황을 줄인다는 지식의 시스템화 관점

합류 후 첫 주 동안 10명 이상의 개발자를 인터뷰했는데, 생각보다 많은 구성원이 위와 같은 문제의식을 공유하고 있다는 점이 놀라웠다. 심지어 이미 여러 차례 조직 내에서 문서화를 시도한 경험도 있었다. 충분히 고무적인 상황이었다. 많은 조직이 문서의 비효율성에 집중하는데, 오히려 이 팀은 문서의 필요성을 인지하고 적극적으로 노력해본 경험이 있었기 때문이다. 이는 테크니컬 라이터로서 내가 가진 문제의식을 이미 경험해 봤고 공감하는 사람들이 많다는 것을 뜻했고, 실제로 그랬다.

사용자의 행동을 제약하지 않고 따라가기

그러면 단순히 존재하는 모든 지식을 모아 정적인 문서를 만들면 될까? 개발자들 스스로도 그렇게는 안된다고 1:1 혹은 포커스 그룹 인터뷰에서 이야기 했고 나 역시 그걸로는 충분하지 않다고 생각했다.

팀 내 개발자들이 작성한 문서를 사용하게 하는 시도는 이미 수차례 실패했고 Slack 채널이나 동료에게 먼저 묻는 행동이 지속됐다. 그렇다면 '문서를 기반으로 한 업무 방식'이라는 개념을 재정의해야 하는 것 아닐까?

개발자는 문서를 읽고 깊이 있는 지식을 얻고 싶어할 때도 있지만, '업무할 때'라는 조건 안에서는 대부분 빠르게 문제를 해결하고 싶어한다. 그래서 팀 내 개발자가 하는 행동은 온오프라인에서 '질문한다'는 것이다. 빠르게, 원하는 정보를, 내 문제와 맥락을 이해하는, 믿을 수 있는 동료들로부터 얻고 싶기 때문에 자연스러운 행동이다. (그리고 대부분의 조직에서 일어나는 일이기도 하다.) 그래서 나는 개발자들이 기존에 하고 있는 방식대로 질문하면서 업무를 하되, 그 과정에서 발생하는 지식의 편차를 줄이고 효율적인 정보 관리가 이루어질 수 있도록 문서가 이를 지원해야 한다고 생각했다.

이 목표를 위해 최근 가장 흥미를 가지고 집중하고 있는 일은 AI 툴에 문서를 학습시키고 질문에 올바른 대답을 하게 하는 작업이다. 사람보다 더 신뢰할 수 있는 문서를 만들고, 그것을 기반으로 빠르게 원하는 정보를 얻을 수 있다면 어떨까? 때로 무언가 깊이 있게 이해하고 싶다면 방문해서 시간을 들여 읽어보기도 하고 말이다.

문서를 학습한 AI, AI가 원하는 문서

그래서 AI에 문서를 학습시키고, 이를 통해 문서와 Slack에서 올바른 답변을 제공할 수 있도록 하는 작업을 하고 있다. 이미 토스페이먼츠 개발자 센터를 개편하며 추가한 기능이라 익숙했지만, 당시에는 단순히 기술 지원으로 질문하러 가는 사용자의 수고를 덜어주기 위함이었다. 지금은 앞서 이야기한 맥락 때문에 좀 더 구체적인 기대를 가지고 진행하고 있다.

물론 AI 툴이 양질의 답변을 제공하려면 탄탄한 기반 지식이 필요하다. 그래서 양적으로나 질적으로나 문서를 작성하는 작업에도 많은 노력을 기울이고 있다. 그런데 문서를 작성하면서 문득 이런 생각이 들었다. 만약 사람들이 AI 툴에 질문을 해서 답을 얻는 것이 익숙한 행동이 된다면, 이제 '훌륭한' 문서란 AI가 잘 학습할 수 있는 문서가 아닐까? 그렇다면 AI가 잘 학습할 수 있는 문서는 어떤 요소를 갖추어야 할까? AI에게 필요한 테크니컬 라이팅은 뭘까?

이 질문이 올바른지에 대해서는 아직 확신이 서지 않지만, 현재 병행하고 있는 다른 업무 과정에서 개발자가 쓴 초안을 리뷰하며 이와 관련된 생각이 계속 이어졌다. 문서 리뷰를 시작하고 초반에는 기능에 관한 핵심적인 내용이 아닌 사소한 표현, 표기 등을 많이 리뷰해야 했다. 표현과 표기를 규칙화 하는 것은 전통적으로 테크니컬 라이팅에서 중시하는 부분이고, 나 역시 이와 관련해 여러 규칙을 만들어 두었다. 다만 이런 원칙을 개발자가 학습하고 충분히 작성하는데는 시간과 노력이 든다. '원칙'이란 결국 직관적이지 않은 것들을 규격화해서보다 명확하게 이해하고 적용할 수 있도록 도와주는 것이기 때문이다.

핵심적인 부분에 대한 글쓰기 역시 문제가 있었다. 초안의 퀄리티가 높지도, 일정하지 않았다. 초안의 퀄리티를 높이기 위해서도 충분한 시간과 노력이 필요한데, 개발자들이 노력을 들이면 '좋다'는 것과 별개로 현실적인 다른 방법은 뭐가 있을지 생각해 볼 필요가 있었다.

그래서 시그니처(함수나 클래스의 동작을 표현한 것으로 '수학 공식'과 비슷한 개념이다. 수학 공식이 특정 문제를 해결하기 위해 어떤 값들을 입력받아 결과를 산출하는지 정의하듯이, 함수나 클래스의 시그니처는 그 기능이 어떤 입력을 받아들이고 어떤 출력을 제공하는지 정의한다.)와 코드 예제만 있어도 jsdoc 형식에 맞춰 문서 초안을 쓸 수 있도록 커스텀 GPT를 만들어 제공했다.

개발자들에게 라이팅 원칙을 교육하고 리뷰를 통해 학습을 돕는 것도 물론 중요하지만, 이를 프롬프트에 잘 담아 자동화하는 것이 개발자에게도 테크니컬 라이터에게도 더 효율적으로 느껴졌다. 실제로 자동화 이후 내가 리뷰해야 하는 문서 초안의 퀄리티는 훨씬 높아졌다. 사소하게 고쳐줘야 하는 자잘한 띄어쓰기나 맞춤법 리뷰는 거의 사라져서 더 중요한 이야기를 나눌 수 있었다. (*개인적으로 기술 문서를 작성하기 위해 띄어쓰기와 맞춤법을 외우려고 노력하는 것은 불필요하다고 생각한다. 규칙이 변할 수 있고, 직관적이고 일관된 규칙이 적용되지 않는 예외가 많고, 외래어 표기법 같이 실제 가독성을 떨어트리기도 하는 부분을 리뷰해야 하기 때문이다. 게다가 맞춤법 검사기로 이미 자동화 되어 있어서 사람이 직접 할 필요가 없다.)

---

이런 경험을 하면서 테크니컬 라이터는 이제 단순히 기술과 관련된 글을 작성하는 것, 글쓰기 원칙을 만드는 것 이상으로 더 중요한 역할을 고민해야 한다는 생각이 들었다. 가장 간단하게는 이미 하고 있는 것처럼 AI 사용을 위해 글쓰기 원칙을 모두 프롬프트화 하는 데 집중할 수 있다. 혹은 코드로부터 문서가 쉽게 만들어지는 파이프라인을 직접 만들고 고도화 하기 위해 엔지니어링을 다시 배워야 할 것 같다는 생각도 한다.

이렇게 직접 쓰고, 리뷰할 내용이 줄어든다면 테크니컬 라이터는 어떤 일에 집중해야 할까? 아마도 글쓰기 그 자체는 아닐 것이다. 그런데 이 말은 업의 본질적인 가치가 퇴색된다는 뜻은 아니다. 단순히 AI나 자동화와 관련된 변화 때문만도 아니다. 문서를 생산하고 사용하는 개발자들의 경험을 이해한다는 본질적인 업의 가치를 따라가다보면 글쓰기 외에 보이는 것들이 많기 때문이다. 질문하는 방식을 유지하면서 문서를 잘 활용할 수 있게 경험을 설계한다든지, 문서 작성을 위한 규칙을 외우는 대신 핵심적인 기능 설명에 집중할 수 있게 돕는다든지 하는 일들이 내게는 그랬다.

그동안 테크니컬 라이터는 개발자를 가장 가까이에서 지켜보면서 그들의 학습/일 경험에 대한 중요한 고민을 해왔다. 그 고민을 기반으로 할 수 있는 일과 역할을 더 넓게 재정립해볼 필요가 있다고 생각한다. 아직 답이 나오지 않은 질문에 가깝지만, 테크니컬 라이터라는 직업의 이름에 얽매이기 보다는 테크니컬 라이터가 그동안 해 온 일의 본질에 좀 더 다가가는 고민을 계속 해보고 싶다.