업무적 글쓰기가 고민인 당신을 위하여 - 개발자의 글쓰기
업데이트:
개발자의 글쓰기라니, 그야말로 양심에 찔리는 주제가 아닐 수 없다.
개인 블로그는 일 년 넘게 방치하고, 사내 Wiki 도 작업에 치인다는 변명으로 미루기 일쑤인 엔지니어인지라.
IT 업계에 몸담고 있는 주니어라면 들을 가치가 있다는 소개글에 홀린 듯 참석한 세미나이다.
한빛미디어 본사에서 진행한 강의는 Docs for Developers 도서도 저렴하게 구매할 수 있었다. 오랜만에 이북이 아닌 종이책을 샀으니, 짬짬이 즐겁게 읽어봐야겠다.
### 기술문서의 뼈대를 잡는 3단계 Step 1. 누구를 위한 문서인가? - 독자 분석, 페르소나 분석 Step 2. 문서로 알 수 있는 내용은 무엇인가? - 행위 분석, 시나리오 분석 Step 3. 문서를 접하는 이가 경험할 만한 어려움은 무엇이고, 그 땐 어떻게 해결해야 하나? - 문제점 분석(해결책 제시) {: .notice--warning} 예를 들어 Wiki 에 글을 쓸 때, Grafana 모니터링 설정 가이드를 써야겠다! 는 생각은 하지만 누가 읽을지, 이 글을 읽는 사람이 이해가 안된다거나, 가이드대로 따라하다가 잘 안될 때는 어떻게 해야할까? 까지 생각했던 적은 없던 것 같다. ~~뭐 우리 팀 사람들인데 다들 이해하겠지… 모르면 물어보겠지(?)~~
하지만 내가 독자 입장이었을 때, 머리 속에 물음표가 떠오르던 글이나, 내용대로 진행하다가 도중에 문제에 직면했을 때 어떻게 해야 할 지 몰라서 당황했던 적이 심심찮게 있었던 걸 생각하면 굉장히 안일한 태도가 아니었나 싶다. 강사님이 들어주신 레시피의 예시처럼 웬만큼 요리 센스가 있는 사람이 아닌 이상 레시피대로 음식을 만들더라도 기대한 맛이 나지 않는 경우가 많은 것처럼. 능숙한 엔지니어라 해도 처음 다루는 툴의 가이드에서 헤맬 수도 있는 법. 이 문서를 읽을 대상을 먼저 지정하고, 그 대상에 맞춰 글의 난이도부터 다양한 경우의 수를 기재해주는 것이 친절한 Wiki 작성자일 수 있겠지.
### 글을 잘 쓰기 위한 노력 5가지 글쓰기에는 나름 자신이 있던 나였지만 지금은 글쎄… 하고 돌아보게 된다. 쇠도 방치하면 녹슬듯 실력도 갈고 닦지 않으면 사라지게 되는 법. 기술 공부만큼 글을 쓰는 노력도 게을리하면 안 될 것을 괜시리 반성하게 되었다.
1st. 좋은 표현 많이 익히기 - 편안하고 자유롭게 정보를 받아들이되, 비판적인 사고를 게을리하지 않는다 {: .notice--warning} ”좋은 표현을 익힌다는 것은 KPI 를 잴 수 없는 일” 이라는 강사님의 표현이 마음에 와닿았다. 특히 정보를 접할 때 반드시 업무나 기술 관련 정보가 아니어도 된다는 말은 뜨끔했다. 요즘 책을 고를 때 소설책이나 다른 비문학 서적은 기술 서적이 아니니까라는 변명으로 일부러 멀리했던 기억이 떠올랐기 때문. 편안하고 자유롭게 많은 정보를 받아들이는 태도가 풍부한 작문의 토대가 되겠지 싶었다.
그리고 사실 이 업계에 들어오고 나서 무조건적으로 받아들이기만 하는 성향이 강해진 것 같은데, 정보를 받아들일 때 ‘나라면 어떻게 표현할까? 뭘 할까?‘ 라는 생각의 필터를 거치는 것이아먈로 진짜 내 정보를 만드는 방법인 것 같다. 근육을 단련하는 것과 같다는 한 마디는 운동하는 사람으로서 공감하기 쉬웠고. 쉽지 않은 습관을 내 것으로 만들기 위해서는 귀찮고, 힘들지만 끊임없이 하는 것이 중요하니까. 수용하는 것은 쉽지만, 나라는 필터를 거쳐야만 진짜 내 것이 되는 거겠지.
2nd. 비문학적 글쓰기 - 메모와 문서화는 다른 것이다 {: .notice--warning} 사실 가장 찔린 내용은 ’번역체 멀리하기‘였다. 어쩔 수 없는걸, 아직 우리나라에서 일한 기간보다 일본에서 일한 기간이 더 긴데… 는 변명이고, 책을 많이 읽지 않으니 아직도 일본식 표현에서 벗어나지 못했다는 게 진실이다. 지나치게 딱딱하고 한자 표현이 많은 글은 읽는 사람도 한 발자국 멀어지게 할 수 밖에. 되도록 읽기 쉽게 글을 쓰는 습관은 당장 사내 Wiki 를 쓸 때부터 시작해야겠다고 결심했다(제일 많이 쓰는 ~에 관한, 기재하다 는 최대한 피해봐야지).
메모와 문서화는 다른 거라고 말씀하셨는데, 이건 위에서도 언급된 ’독자‘를 생각한 글쓰기와 통하는 내용인 것 같다. 독자가 누구든 공통적으로 필요한 것은 ’간결함‘ 아닐까? 팁으로 들은 능동태로 쓰기라던가, 핵심 문장 성분만 남기기라던가. 글을 쓰는 나야 이해하고 있는 내용이니까 대강 알아볼 수 있게 쓰면 되겠지만, 타인에게 내 글을 읽게 한다는 것은 쉽고 단순하지 않으면 안된다. 간결함에서부터 글이 시작된다, 는 문서를 쓰기 시작할 때 가장 먼저 떠올려야 할 내용일 것 같다.
3rd. 일관성 있는 글쓰기 {: .notice--warning} 솔직히 ’설루션‘이 표준어일 거라고 누가 생각하겠어? 백이면 백 ’솔루션‘이라고 쓰지. 우리는 국립국어원 사람이 아니니까 현실적이고 읽는 사람에게 맞는 표현을 쓰는 걸 지향한다는 게 신선했다. 역시 독자가 읽기 쉽게 쓰는 것이 중요한 법!
더불어 자신의 Writing Style 에 대한 고찰도 필요한 것 같다. Writing Style 은 Coding Convention 과 같다고, 쓰는 사람의 개성이 드러나는 글이 읽기도 쉽고 인상에 남지 않을까?
강사님이 추천해 주신 참고할 만한 Writing Style 은 단연 Apple 과 Microsoft 라고 한다. 뭐, 두 회사처럼 문체나 표현을 사전처럼 만들어 사용하지는 않더라도, 나를 드러낼 수 있는 일관성 있는 글 표현을 지니는 것은 필요할 듯 하다.
4th. 글도 테스트가 필요하다 {: .notice--warning} 글쓰는 게 망설여지는 가장 큰 이유는 역시 완성도 있게 글쓰는 게 부담스럽기 때문 아닐까? 적어도 나는 그런데… 그만큼 글을 쓰더라도 몇 번씩 읽어보고 첨삭하는 게 중요하다고 한다.
첨삭이라면 다른 사람에게 받아보는 게 기본이긴 하지만, 내가 직접 첨삭할 수도 있다고 한다. 예를 들면 시간이나 장소, 읽는 매체 같은 것들을 바꿔서 읽어보는 것. 컴퓨터 모니터로만 읽는 게 아니라 태블릿에 넣어서도 읽어보고 인쇄해서도 읽어보는 것처럼. 같은 글이라도 다양한 방법으로 읽어보면 눈에 보이는 것들도 달라질 수 있을 것 같다.
5th. 글쓰기를 넘어서는 정보 전달 {: .notice--warning} Interrupted Demo 처럼 사용할 수 있는 다양한 수단을 사용해서 정보를 전달하는 것도 도움이 된다고 한다. 예를 들면 이런 걸까? 가이드를 쓸 때 글로만 쓰는 게 아니라 실제 화면을 캡쳐해서 함께 보여준다거나, 작업 안내 공지를 쓴다면 볼드체나 이텔릭체를 활용해서 핵심 내용을 한 눈에 알 수 있도록 표현한다거나 하는 것들. 같은 내용을 쓰더라도 좀 더 효과적으로 내용을 전달할 수 있다면 그 방법을 택하는 것이 좋겠지!
글쓰기의 중요성은 비단 기술적인 내용의 전달에 그치지 않는다. 지금 내가 서 있는 곳을 알고, 내가 가는 길의 방향이 옳은지 프로파일링할 수 있는 수단이 글쓰기라는 것. 계획에 기초해서 글을 써내려 가다 보면, 내가 거쳐온 과거의 흐름을 되돌아봄과 동시에 앞으로 나아갈 방향을 판단할 수 있을 것이다.
Technical Writer 라는 직업을 들어본 적은 있지만, 어떤 업무를 하고 전문적인 기술 문서를 쓸 때 어떻게 접근하는지 등에 대한 내용을 깊이있게 들을 수 있었던 기회는 흔치 않아 의미 있는 세미나였다. 무엇보다 IT 종사자로서의 글쓰기에 대한 견해를 들을 수 있어서 생각보다도 더 참석하길 잘했다는 생각이 들었다.
엔지니어로 일하며 기술을 익히는 데만 급급했던 나였지만, 앞으로 글을 쓰는 것에 비중을 좀 더 두고, 또 쓰는 행동에 두려워하지 않도록 해야겠다(결심의 첫 발자국으로 오랜만에 이 글도 작성하는 거기도 하고!). 마지막으로 질의응답 시간에 강사님이 전해 주신 문서화의 본질로 글의 마무리를 짓는다.