HanBitN MSA?
한빛N MSA(Micro Seminar Assemble)는 한빛미디어 디지털콘텐츠개발연구소에서 준비한 세미나 시리즈다. 학교와, 학원 등에서 다루지는 않지만, 현업에서 일을 할 때 필요한 지식, 기술, 정보 등을 전달하는 걸 목표로 진행되는 세미나다.
업무적 글쓰기가 고민인 당신을 위하여
모든 사람들의 시간은 중요하기에, 문서화가 더욱 강조된다.
글쓰기는 생각보다 상당한 노력을 필요로 한다. 세미나 리뷰글을 작성할때마다 원하는 방향성대로 글이 나오지 않으면 몇 번이고 글을 읽고 수정하는 과정을 거쳤다. 이와 비교했을때 개발자들이 작성해둔 코드를 잘 설명하기 위한 문서화는 더 어려운 일이라고 할 수 있다.
개발자가 코딩을 잘하는 것은 기본 소양이지만, 작성한 코드를 다른 개발자에게 잘 설명하는 것은 또 다른 영역이다. 그런만큼 문서화를 실제로 적용하는 과정에서 고민이 생기기 마련이다. 이번 세미나는 이와 같은 고민을 가진 개발자들에게 도움이 될만한 팁들이 소개되었다. 그 내용이 무엇인지 한 번 알아보자.
본 게시글에 사용된 강의 자료는 한빛미디어의 지원을 받았습니다.
3대 부채
우리가 회사를 다니면서 경험하는 '3대 부채'가 있다. (투자금, 기술부채, 지식부채)
회사 시스템 구축을 위해 초기에는 투자금을 활용하고, 빠르게 시제품을 만드는 과정에서 몇몇 부족한 점과 엉성한 부분이 존재해 기술부채가 쌓이게 된다. 일반적으로 투자금과 기술부채 까지는 자주 언급되는데, 그 외에도 '지식부채'라는 개념이 있다. 여기서 지식부채는 문서화를 의미한다.
우리 모두는 한때 신입사원이었다. 업무를 배우기 위해 사수나 부사수, 그리고 시니어 분들에게 여쭤보며 배운 경험이 많았을 것이다. 그리고 이런 상황에서 물어보기 곤란한적도 분명히 있었을거라 추측한다. 이런 상황에서 문서화를 해뒀다면 불필요한 정보를 걸러내고, 정말 필요한 이야기들만 정갈하게 전달할 수 있다.
근데 평소에 문서화를 안해뒀다면 부채가 된다. 혹자는 문서화를 안하고 다 말로 할거라며 '구전주도 개발'을 말하는데, 나중에 가보면 이게 다 부채로 잡힌다. 한꺼번에 문서화를 하려면 너무나 부담스럽기 때문인데, 이런 의미에서 강연자분이 문서화를 지식부채라고 하셨다.
엘리베이터 피치 == README
엘리베이터 피치를 들어본적이 있는가? 엘리베이터에서 중요한 사람을 만났을 때 자신의 생각을 요약하여 짧은 시간에 전달할 수 있어야 한다는 의미로 지어졌다. 강연자분께선 깃헙 오픈소스 레포에 있는 README도 동일한 역할을 한다며 강조하셨다.
어떤 종류의 오픈소스 프로젝트라 할지라도, 성공적인 프로젝트라면 결코 문서화를 등한시 하지 않는다.
README는 이게 과연 내가 필요로 하는 프로젝트인지 빠르게 확인하는 근거가 되기 때문인데, 뿐만 아니라 프로젝트 참여자를 더 많이 모으려면 README를 포함해 전반적인 문서화가 잘 되어 있어야 한다. 그렇다면 이런 문서화를 잘하기 위해선 어떤 노력이 필요할까?
기술문서 뼈대잡기 '3'단계
당신은 임직원 전용 디지털 커피 주문 서비스를 만들어야 하는 팀의 개발자다.
먼저 이 앱을 사용할 사람들은 크게 3가지 부류로 나뉜다.
- 음료를 주문할 손님
- 음료를 제조할 바리스타.
- 기기 고장을 수리하는 엔지니어.
세 부류의 사람들을 대상으로 서비스 제공을 해야 하는 상황에서, 어떻게 하면 각 대상별로 사용자 가이드를 만들 수 있을까? 머릿속으로 상상하면서 아래 내용들을 확인해보자.
Step 1. 독자 분석
독자가 누군지를 정말 잘 알아야 합니다.
독자를 잘 아는 방법은 간단하다. 위 사진처럼 카테고리별로 표를 만드는 것부터 시작하면 된다. 여기서 생각해볼건, 각각의 사람들이 시스템이나, 회사의 특정 서비스에 대해 이해수준이 전부 다르다는 점이다. 그말인 즉슨 가이드에 들어가는 세부내용도 세심하게 나눌 필요가 있다.
'아니 얼마나 모르면 이런거까지 하나하나 설명해야돼?'
우리가 문서를 작성하다보면 위와 같은 푸념을 할때가 있는데, 강연자분께선 이 경우 독자분석에 실패한 문서화라고 하셨다. 정말 문서화를 잘하기로 생각했다면 이런 푸념은 나오면 안된다.
사용자는 내가 설명하고자 하는 토픽에 대해 아무것도 모르는게 너무나 당연한 일이다. 이 사실을 잊으면 안된다. 그렇다고 해서 '사용자가 바보냐?'고 한다면 그건 또 아니다. 적어도 이 문서를 바라볼 수 있는 기본 요건은 모두 갖춰야 따라갈 수 있으니, 이 서비스를 누가 사용하는지를 정확히 분석한 다음에, 그들의 눈높이에 맞춰 문서화 하는 과정이 반드시 필요하다.
Step 2. 행위 분석
다음으로는 독자가 할법한 일들, 궁금할법한 내용들을 열거해야 합니다.
주문하는 사용자를 기준으로 얘기해보자. 처음에 사용자가 앱을 설치하는 것부터 시작해 로그인을 거치고, 모아서 주문하기/바로 주문하기, 음료 수령 및 주문시의 에티켓 등 다양한 시나리오가 존재한다.
이 가상의 시나리오에서 생각해야 할 것은 '복지차원'에서 서비스를 제공한다는 점이다. 스타벅스의 사이렌오더 같은 주문 시스템은 고객의 편의를 최대한 고려하며 매출을 극대화 하는 방향으로 디자인되어있다. 반면 이런 복지서비스의 경우 행동강령(code of conduct), 회사의 재무적 상황, 보안 규정 등 다양한 고려사항이 존재한다.
💡 앱 설치를 예로 들어보면, 이런 종류의 앱을 만들 때는 앱스토어에 직접 올리는 경우가 별로 없다. 안드로이드의 경우 APK 파일을 다운로드하고, iOS의 경우 TestFlight 앱을 통해 따로 피드를 다운로드하는 방식을 사용하기 때문인데, 이로 인해 앱 설치가 일반적인 앱과는 매우 다른 절차가 될 수 있다.
앞선 독자 분석을 제대로 했다면 굉장히 디테일한 부분까지 개선해 관련 내용들을 시나리오에 녹여낼 수 있다. 예시로 장기 휴직 후 다시 앱을 사용하려할때, 회사 보안 규정상 앱에 연결된 계정이 비활성화 된 경우가 있겠다.
Step 3. 문제점 분석
독자가 경험할만한 어려움을 열거해야 합니다.
최근 '백종원의 요리비책' 유튜브 채널을 보며 요리를 하나씩 해보는 재미에 맛들렸는데, 레시피를 보고 했는데도 똑같은 맛이 나오지 않아 당황한 적이 있었다. 아무래도 레시피에 명시된 '한 큰술'이 사람마다 이해하는게 제각각이기 때문에 이런 문제가 발생하는데, 가이드를 작성하는 입장에서도 마찬가지다.
가이드를 작성하는 입장에서는 '이때 터치를 하면 어떤 화면이 떠야하고,,,'하는게 당연하게 그려지지만 생각보다 많은 사람들이 그 상황에 놓여있지 않은 경우가 있다. 마치 부모님께 신형 스마트폰을 사드리고 기능을 하나씩 알려드리는데 쉽사리 따라오지 못하시는 느낌과 같은거다.
특히 요즘은 애자일/스프린트 일정에 따라 최소한의 오브젝트만 구현하는 방식을 많이 사용하는데, 이러다보면 당연히 예기치 않은 버그가 그대로 나가는 경우가 있다. 이런 부분 하나하나가 사용자에게 트러블이 될 수 있으니 어떤 문제점이 있고, 해결책이 무엇인지 조사해 표 형태로 정리해놓는 작업이 굉장히 도움이 된다.
💡 정리
-
독자분석
적어도 이 토픽을 다룸에 있어 어느정도의 선수지식을 요구하는지 생각하며 기술. 독자 범위를 너무 넓게 잡으면 문서 쓰기가 힘드니, 필요한 선수지식을 스펙으로 문서에 정리해두자.
-
행위분석
각각의 기능을 열거형으로 쭉 설명해놓고 내놓는 가이드는 그 자체로 완결성 있는 문서지만 사용자들에겐 별로 쓸모없는 정보다. 사용자들은 앱의 모양이 어떻고, 어떤 반응이 일어나는지 관심있는게 아니다. 그렇기에 더욱 시나리오를 가지고 기술하는게 중요하다. -
문제점 분석
세상에 시나리오대로 돌아가는건 없다. 그렇기에 각각의 문제점들을 분석해서 어떻게 해결할 수 있는지 정리해두자.
글을 잘 쓰기 위한 노력 '5'가지
1. 좋은 표현 많이 익히기
위 프로그램들의 공통점은 기존에 나와있던 곡들을 본인의 창법으로 재해석해 다시 부르는 프로그램들이다. 글을 잘쓰기 위한 방법 중 하나는 재해석을 잘하는 것인데, 평소에 최대한 많은 정보를 접하는 과정에서 내 언어와 표현을 써서 이야기 하면 어떻게 표현할 수 있을지를 상상하며 읽어보자. 이런것들이 누적되면 자신만의 어휘력을 높이고 관철하는데 중요한 역할을 하게 된다.
2. 비문학적 글쓰기
여러분들이 쓰시는 글은 정말 다른 사람을 위한 문서일까요?
문학은 글 안에서 즐거움을 찾으려고 기교와 현학적인 표현을 써서 그 자체로 예술인 글을 써내려가는 반면, 비문학은 정보를 전달하기 위한 수단으로 거론된다. 이런 비문학적 글쓰기를 하기 위해 중요한 점은 위 사진에 언급된 내용과 같다. 하나씩 더 자세히 알아보자.
-
날짜와 시점을 항상 명확히 표현하기
정보를 전달하고자 한다면, 특히 그 정보가 시간이라면 상대적인 표현이 아닌 절대적인 표현을 사용해야 한다. '현재'라는 표현을 사용하고 싶어도, 이게 정말 정보를 전달하고 시점을 표현하는 의도의 '현재'를 뜻하는 것이라면 날짜를 명시해야 한다. -
능동태 vs 수동태
어릴때 배웠던 영어 문법이 생각나는 파트다. 둘 중 하나가 절대적인 답이 될 순 없겠지만, 생각보다 수동태를 쓸 일이 많지는 않다. 되도록 간결한 표현을 추구할 때 능동태를 사용할 수 있는 방법은 없는지 고민해야 한다.
- 핵심문장 성분만 남기기
글을 쓰다보면 '만연체'가 되어 마구마구 부풀어올라 힘들게 다 쓰고 봤더니 무슨 말인지 모르겠다 싶은 경우가 있다.리뷰글을 쓰는 지금도 그렇다.이 경우 불필요한 문장성분이 많아 발생하는거니, 정말 필요한 문장 성분을 제외하고는 다 빼서 최대한 간결하게 문장을 써야 한다.언제나 우리는 비문학을 하고 있다는 사실을 명심하자.
-
쉬운 우리말과는 친해지고, 번역체랑은 멀어지기
아직까지 한국어에는 한자어의 잔재가 많이 남아있다. '쓰다'라는 표현을 '기입한다'라는 표현으로 쓴다거나, 지진이 났을때 '여진'으로 표현하는 것 외에도 줄여쓰기를 이유로 과하게 한자어를 많이 쓰는 경우가 있다. 무조건적으로 텍스트의 지면 길이를 줄이는 것에 중점을 두지 말고, 누구나 다 정보를 쉽게 접근할 수 있도록 배려하자.
3. 일관성 있는 글쓰기
일관적인 글쓰기를 위해서는 '문서를 누가 읽고 어떻게 활용하는지'를 먼저 생각해봐야 한다. 우리는 주로 한국인이 보는 문서를 작성하기에 한국어로 말이 안되는 문장을 쓰진 않는다. 그렇다고 해서 맞춤법을 지나치게 강조하다보면 굉장히 이상한 일이 벌어진다.
놀랍게도 위 사진에서 표준어는 '설루션'이다. 표준을 최대한 따르는 것은 당연한 일이지만, 현실에 맞지 않는 문법도 엄연히 존재하는 법이다. 우리가 국문학자거나 국립국어원에서 일하는 사람들이 아니기에, 부적합적인 표준을 따르기 보다는 문서를 읽고 활용하는 사람의 시선에 맞는 표준을 잘 지켜야 한다.
애플의 광고를 보면, 언더독의 입장에서도 불구하고 '우린 우월하고 뛰어나다'는 이미지를 되게 강조한다. 이는 애플 스토어에서 AS하는 분들을 '지니어스'라 부른다거나, 광고에서 '~졌죠'와 같은 문체에서도 쉽게 찾아볼 수 있다.
이런 광고 텍스트를 한 사람이 쓴 것은 당연히 아닐 것이다. 우리가 코드를 작성하기 전 코딩컨벤션을 이야기 하듯이, 카피라이터들 사이에서도 라이팅 스타일이란게 존재한다. 만약 우리가 국립국어원과 협업을 한다면 '솔루션'이란 표현을 틀린 표현이라고 가이드를 작성할 수 있을 것이고, 반대로 일반적인 SW 개발 회사의 라이팅 가이드를 쓴다면 '설루션'을 틀린 표현이라고 작성할 것이다. 이외에도 문체같은 부분도 어떻게 쓰는지 정의해둔다.
이런 라이팅 가이드 스타일을 참조하고자 한다면 어느 회사가 좋을까. 세미나에서는 MS, Apple의 스타일가이드 사이트가 언급됐다. 강연자분의 말을 빌리자면 전자는 정석, 후자는 예쁘게 디자인된 케이스라고 하니 궁금하다면 한 번씩 들어가서 확인해보자.
4. 글도 테스트가 필요하다.
남이 짠 코드에서 발생하는 버그는 잘 찾아내면서 막상 내가 짠 코드에선 쉽게 발견하지 못하는 것 처럼, 자기가 쓴 글을 읽으며 객관적으로 어디가 잘못됐는지를 스스로 찾아내는게 상당히 어려운 일이다. 그럼에도 찾아낼 방법은 있다. 위 항목들을 참고해 어느 부분을 고쳐야 하는지 잘 찾아내보자.
🧑🏻💻: 찾아냈어요! 그 다음은..?
우여곡절 끝에 고쳐야할 부분을 발견했다면, 과연 무엇을 생각하며 고쳐야 할까?
-
타당성: 형식적인 부분에서 완성도와 함께 챙겨야 할 부분이다. 어떤 부분을 서술하며 인용한 자료가 정말 타당한지를 마지막까지 생각해야 한다. 다시 말하지만, 있는 그대로의 사실과 팩트를 전달해야 하는 비문학을 작성한다는 사실을 명심하자. 공상과학이나 문학적인 글을 쓰는게 아니다.
-
맞춤법: 아쉽게도 한국어는 맞춤법을 자동으로 잡아주는 툴이 아직까지도 없다. 최소한의 맞춤법 검사는 돌리고, 워드/브라우저에서 뜨는 빨간줄(맞춤법 검사 기능)을 무시하지 말고 최대한 맞춰보자!
5. 글쓰기를 넘어서는 정보 전달
정보전달의 수단이 반드시 글이어야 할 필요는 없다. 요즘은 유튜브나 인터렉티브 데모, 인포그램, 다이어그램 등 다양한 수단이 있는데 가능한 수단을 최대한 활용하자. 그리고 사진에 나와있는 요소들도 신경써서 검수하자. 언뜻 보기엔 사소한 것들로 보이지만 챙겼을때의 시너지는 크다.
LLM AI의 시대가 왔는데, 과연 글을 쓸 필요가 없을까요?
불과 몇 년 전만 하더라도 검색엔진을 잘 활용하기 위해 키워드나 태그를 어떻게 쓸지 공부했지만, 이젠 이런 것들을 굳이 고려하지 않더라도 chatGPT가 원하는 형태로 답을 돌려주기에, 얼마나 질문을 제대로 잘 하냐가 관건이 되었다. 이 시점에서 어차피 chatGPT가 알아서 글을 써줄건데, 우리가 글을 쓸 필요가 없을까?
오히려 더욱 글쓰기의 중요성이 올라갈 것이다.
chatGPT는 자체적으로 잘못된 내용을 바로잡거나 고치는 능력이 미미하고, 정보주입이 잘못되면 엉뚱한 답을 낼 수 있다. 할루시에이션 같은 증상이 대표적이다. 따라서 우리는 정확하고 올바른 글쓰기에 익숙해져야 한다!
후기
제품을 문서화 하는 것은 거울에 제품을 비추어 보는 것과 같습니다.
제품이 좋지 않으면 그것을 설명하는 문서도 좋을 수가 없습니다.
개인적으로 정리를 워낙 좋아하는 타입이라, 무언가 새로 배운게 있으면 블로그에 기록해두는 습관이 있다. 타인에게 보여줄 글을 쓰다보면 이걸 어디까지 해야하나 싶기도 하고, 초안을 썼다 지웠다를 반복하며 괜히 시간만 날린 것 같다는 생각을 많이 하곤한다. 그래도 이런 글은 마감이 없기에 괜찮았다. 문제는 기한이 정해져있는 경우였는데, 마감 일정에 쫓기며 문서가 프로젝트 속도를 따라가지 못해 중간에 폐기한 경험이 있다.
돌아보면 문서화를 팀원들과 분담하지 않고 내가 단독으로 했던게 패착이라 생각한다. 이런 경험이 있던 만큼 이번 세미나를 통해 좀 더 얻어가는게 있을까 기대하며 세미나 장소에 도착했는데, 지금까지 진행한 세미나들에 비해 사람들이 압도적으로 많았다. 그만큼 업무적 글쓰기에 다들 어려움을 겪는 것이라 이해했다.
세미나 자체의 내용은 '업무적 글쓰기'지만, 이에 관련된 내용보다도 세미나를 듣고 나서 논리적인 글은 체계적인 준비를 통해 탄생한다는 생각을 하게 됐다. 그럼에도 한번에 만족하는 글을 쓰기가 힘들게 분명하니, 여러번의 퇴고를 거치며 글을 작게작게 쓰는 연습을 좀 해봐야겠다.
세미나 이후에 참여자들로부터 취업 준비를 위한 문서화 준비, 주니어와 시니어간 소통할 수 있는 글을 쓰는 방법, 문서 작업 툴 등 다양한 질문이 나왔다. 이외에도 이번 리뷰글에 녹여내지 못한 내용들이 있으니 궁금하다면 아래 링크로 들어가 확인해보자.
