Docker Desktop

Homebrew

iTerm2

애플 실리콘 M1

하드웨어와 소프트웨어에 숨어 있는 언어

CODE 코드

웹개발 관련
The Plan for React 18 : React에서 다음 메이저 버전인 React 18 작업을 시작했고 워킹 그룹을 만들어서 18에 대해 논의하기 시작했다. React 18에는 더 적은 렌더러를 위한 자동 배치와 Suspense의 SSR 지원 등의 개선이 추가되고 Concurrent 기능의 옵트인을 지원하는 첫 릴리스가 될 것이라고 한다. React 18 Alpha 버전을 릴리스해서 테스트해볼 수 있다.(영어)
React 18: 렌더링 최적화를 위한 자동 배칭 : Dan Abramov가 React 워킹그룹에 작성한 Automatic batching for fewer renders in React 18을 번역한 글이다. Batchin은 여러 state 업데이트를 하나의 리렌더링으로 묶어주는 것을 의미하고 이를 통해 성능을 바로 개선할 수 있다고 한다. React 18dptjsms createRoot로 자동 배칭을 할 수 있게 되었고 자동 배칭을 원하지 않는 경우와 Hook, Class와 사용할 때의 영향에 대한 설명도 잘 나와 있다.(한국어)
CSS for Web Vitals : Web Vitals를 최적화 할 수 있는 CSS 기법을 간단한 페이지를 최적화하면서 설명한다. sticky로 상단에 붙어 있던 쿠키 배너를 하단에 fixed로 고정해서 CLS를 개선하고 이미지로 된 배경 이미지를 CSS 그라디언트로 변경해서 LCP를 개선하고 폰트 로딩으로 인한 레이아웃 변경을 줄이기 위해 @import 대신 <link> 태그를 사용한다. 상황별 문제를 찾아서 개선하는 과정을 보여주어서 Web Vitals를 개선하는 접근을 전체적으로 보여주고 있다.(영어)
Yarn Berry 플러그인과 “since” : Yarn Berry에 추가된 플러그인 기능의 사용법을 설명하고 토스 프론트엔드에서 "since"라는 플러그인을 만드는 과정을 설명하고 있다. 이전에 yarn 1과 Lerna를 사용해서 모노 레포에서 변경사항이 있는 서비스만 찾아낼 수 있게 Lerna의 --since 옵션을 사용하고 있었지만, Yarn Berry는 Lerna와 같이 쓸 수 없었고 Lerna가 이제 유지보수가 잘 되지 않으므로 모노 레포에서 특정 커밋 이후에 변경사항이 있는 워크스페이스만 찾아내고 명령어를 실행하는 since라는 플러그인을 만들었다고 한다.(한국어)
그 밖의 개발 관련
ArchUnit - UnitTest로 아키텍처 검사를 : 아키텍처 구조와 규칙을 쉽게 정의하고 검사해주는 ArchUnit의 사용법을 설명한다. ArchUnit의 테스트를 작성해서 의존관계와 상속 관계 등을 검사하고 레이어 아키텍처 등을 검사할 수 있는데 선언형/명령형으로 검사할 수 있으면 AssertJ와 연동할 수도 있다. 실제 네이버에서 Support 패키지는 다른 패키지를 의존하면 안 된다는 규칙이나 API 문서화를 위한 속성을 통일시키는 등의 규칙을 만들어서 프로젝트를 검사하게 했다고 한다.(한국어)
Microsoft has built an AI-powered autocomplete for code using GPT-3 : GPT-3 관련 기술의 라이센스를 가지고 있는 Microsoft에서 엑셀에서 수식을 만들어주는 Power Fx를 오픈소스로 공개했다. Power Fx를 통해서 자연어를 입력하면 GPT-3를 이용해서 쿼리문을 만들어준다고 한다.(영어)
폭발적인 사용자 증가로 마주한 성능 저하 2종 해결하기 : 유니크굿컴퍼니라는 회사에서 운영 중인 리얼월드 플랫폼의 한 게임이 트위터를 타고 갑자기 많은 사용자가 방문하면서 겪은 성능 문제를 해결한 과정을 적은 글이다. 처음은 큐의 메시지의 양을 제대로 소비하지 못하면서 지연되는 문제였고 두 번째는 데이터베이스 커넥션 풀을 충분히 설정하지 못해서 타임아웃이 발생한 문제였다. 알고 나면 해결책이 간단하지만, 갑자기 트래픽이 증가하면 없던 문제도 생기게 마련이라 갑자기 대응한 이야기가 재미있다.(한국어)
인프라 관련
Toward Vagrant 3.0 : Ruby로 작성된 Vagrant의 기능을 유지하면서 3.0을 준비하면서 Go로 포팅 중이라고 한다. 앞으로 2.3과 2.4에서는 호환성을 깨뜨리지 않을 것이지만 3.0에서는 호환성을 유지하면서도 새로운 설정 방법을 도입할 것이라고 한다. Go로 포팅된 3.0에서는 서버-클라이언트 모델이 도입되고 새로운 플러그인 API도 추가될 것이라고 한다. Vagrant의 유용함이 이제는 많이 줄었다고 생각하는 데 적극적으로 Go로 포팅하면서 개선될 Vagrant가 기대된다.(영어)
New from the CNCF Sandbox : kubelist 뉴스레터에서 최근 CNCF의 TOC에서 Sandbox 프로젝트로 승인한 프로젝트를 정리했다.
Antrea: CNI(Container Network Interface)와 Kubernetes NetworkPolicy를 pod 수준에서 구현한 VMWare의 프로젝트
ChaosBlade: 카오스 엔지니어링 시나리오를 생성하고 쉽게 사용할 수 있게 하는 알리바바의 프로젝트
WasmEdge Runtime: 엣지 컴퓨팅을 위한 WebAssembly 런타임
Vineyard: 인메모리 불변 데이터 매니저
Fluid: 분산 데이터 세트 오케스트레이터/엑셀러레이터
Submariner: 다중 Kubernetes 클러스터를 연결하고 서비스 디스커버리도 제공하는 프로젝트
GKE CNI Performance benchmark : Kubernetes에서 사용할 수 있는 CNI 중 Kubenet, Calico, Cilium을 Idle 상태, 트래픽을 줄 때의 상황 등에서 네트워크 성능, CPU/램의 사용량 등을 비교한 글이다. 각 CNI의 특징에 따라 성능을 비교해서 볼 수 있다.(한국어)
Amazon ECS Anywhere 시작하기 – 정식 출시 : Amazon의 컨테이너 서비스 ECS를 온프레미스에서 사용할 수 있는 Amazon ECS Anywhere가 정식 출시되었다.(한국어)
볼만한 링크
데이터 로그 설계, 데이터 로깅, 이벤트 로그 설계, 데이터 QA의 모든 것 : 서비스에서 데이터 추적을 위해 많은 로그를 쌓게 되는데 이 데이터 로그의 설계부터 QA까지 기획자, PM, 마케터들이 이해할 수 있게 정리한 글이다. 데이터 로깅을 하기 위해 필요한 상식과 사용할 수 있는 플랫폼들도 정리되어 있고 서버 로그와 클라이언트 로그의 차이, 웹이나 앱의 로깅 특성도 잘 정리되어 있다. 이벤트 로그를 어떻게 설계하는 방법과 예시도 잘 나와 있어서 데이터 추적에 대한 이해도를 높이거나 서비스에 로깅 설계를 할 때 참고해서 정리하기 좋은 글이다. (한국어)
Summary of June 8 outage : 지난 6월 8일 CDN인 fastly가 장애 나면서 수많은 서비스에 영향을 주었다. 사용자의 유효한 설정이 숨겨져 있던 버그를 실행하면서 발생했고 1분 이내에 이 문제를 발견해서 해당 문제를 격리 한 뒤에 49분 후에 95%의 네트워크를 복구했다고 한다.(영어)
F8 Refresh: 개발자가 주인공인 이벤트 : 페이스북이 자사의 콘퍼런스 F8에서 새로운 API 및 기능을 공개했다.(한국어)
Instagram 용 Messenger API 공개
WhatsApp Business API 공개
Messenger를 이용한 로그인 커넥트로 로그인 흐름에서 메시지를 주고받을 수 있게 됨
모바일 AR 플랫폼인 Spark AR에 Multipeer API 추가
AWS 대회에서 1등 했습니다! : AWS에서 고객사와 진행하는 게임데이에 참여해서 1등을 차지한 후기를 적은 글이다. AWS에서 설정한 어떤 환경 아래에서 AWS 인프라를 이용해서 서비스를 제공하면서 계속 주어지는 문제를 해결하는 식으로 진행되는데 다음 대회를 위해서 자세한 문제까지는 공유하지 못했지만, 진행 방식과 적용한 내용이 나와 있어서 대회 방식을 이해할 수 있다. 나도 이 대회에 참가했는데 어떤 대회인지 사전에는 몰랐지만, 무척 재밌고 잘 구성되어 있었다.(한국어)
IT 업계 뉴스
Stack Overflow Sold to Tech Giant Prosus for $1.8 Billion : 개발자가 질문 답변을 하는 사이트인 Stack Overflow가 유럽에서 가장 큰 투자 회사인 Prosus에 18억 달러에 매각되었다.(영어)
'빅데이터 강자' 클라우데라, 사모펀드에 팔렸다 : 사모펀드가 클라우드 데이터 플랫폼을 제공하는 Cloudera를 53억 달러에 인수했다. 2017년 Cloudera는 뉴욕증시에 상장했지만 이번 인수로 비공개 기업으로 바뀌게 되었다.(한국어)
Day One at Automattic : Wordpress를 운영하는 Automattic이 노트 앱인 Day One을 인수했다.(영어)
프로젝트
SF Symbols 3 : Apple에서 San Francisco 폰트와 어울리는 아이콘 라이브러리를 공개했다. 3 버전에서 600개의 새 아이콘이 추가되었다.
Elevator Saga : 엘리베이터를 프로그래밍해서 도전 과제를 푸는 게임이다. 예를 들어 일정 시간 내의 몇 명의 사람을 이동시켜라 같은 미션을 엘리베이터 프로그램을 작성해서 푸는 게임이다.
버전 업데이트
Terraform v1.0 GA : 서버 인프라 설정 도구, 릴리스 공지
Grafana v8.0 : 매트릭 대쉬보드, 릴리스 공지
Grafana Tempo v1.0.0 GA : 분산 트레이싱 백엔드, 릴리스 공지
Electron v13.0.0 : 크로스 플랫폼 데스크톱 애플리케이션 플랫폼, 릴리스 공지
Lighthouse v8.0.0 : Progressive Web Apps용 성능 분석 도구, 릴리스 공지
Vivaldi 4.0 : 웹 브라우저, 릴리스 공지
Waypoint v0.4.0 : 빌드, 배포, 릴리스 워크플로우, 릴리스 공지
Spring Native v0.10.0 : GraalVM을 이용한 스프링 네이티브 이미지 컴파일러, 릴리스 공지
Gradle v7.1 : Java 빌드 도구, 릴리스 공지
OBS Studio v27.0 : 비디오 녹화 및 라이브 스트리밍 프로그램, 릴리스 공지
Node.js v16.3.0 (Current) : 자바스크립트 런타임, 릴리스 공지
Deno v1.11.0 : TypeScript 런타임, 릴리스 공지
pnpm v6.7.1 : Node.js 패키지 매니저, 릴리스 공지
Rollup v2.51.0 : JavaScript 번들러, 변경 사항
Harbor Operator v1.0.0 : 컨테이너 이미지 저장소의 오퍼레이터, 릴리스 공지
댓글 쓰기

기술 뉴스 #176 : 21-06-15

매년 6월이 되면. 이제는 자동적으로 떠오르게된다. 오. 노마드코더 창립기념일(!?) 이구나.와. 벌써 4년이 되었다. 정말이지 적응이 안된다. 이게 뭐랄까 딱 각잡고. 강남에 사무실 내고. 시장 조사 하고. 비즈니스 모델을 딱 써가지고 시작한 사업이 아니라. 어? 어어어어엌? 하다가 만들어진 상황이라 더더욱 그러하다. (그렇게 함께 시작한 사람이 남편이

'노마드 코더'를 운영한 지 4년이 되었다 - 아우. 경쟁 너무 빡세.

안녕하세요 리멤버를 서비스하고 있는 드라마앤컴퍼니의 개발실 리더 김담형입니다.
지난 6월 7일 진행된 AWS GameDay에서 저희 리멤버 팀이 1위를 차지했습니다! 
좋은 성적을 거뒀다는 사실도 만족스럽지만, 게임 자체의 퀄리티가 너무 좋아서 저희 모두 정말 시간 가는 줄 모르게 재미있는 경험을 했습니다. 이번 글에서는 AWS GameDay가 낯선 분들을 위해 간략하게나마 어떤 내용의 대회였고 또 저희가 대회 중에 문제들을 어떻게 해결했는지 설명해 드리고자 합니다.
대회 설명
AWS GameDay는 AWS 아키텍처에서 생길 수 있는 다양한 문제들을 게임화된 환경에서 직접 대처하며 AWS에 대한 이해를 높일 수 있는 인터랙티브 콘텐츠입니다. 참여한 팀마다 모의 서비스가 운영되고 있는 AWS 계정이 하나씩 주어집니다. 운영되고 있는 서비스에는 예상하지 못한 장애, 트래픽 증가 등 여러 돌발상황이 발생하기 때문에 AWS 아키텍처를 변경하여 안정적으로 서비스를 운영해야 하는 대회입니다. 한 팀은 최대 5명으로 구성됩니다. 고퀄리티로 만들어진 대회인 만큼 아마 해당 내용 기반으로 대회가 또 열릴 것 같아 너무 상세한 내용은 적지 못하는 점 양해 부탁드립니다 
제가 굉장히 고퀄리티라고 생각했던 첫 이유는 바로 몰입을 위한 상황설정이었는데요, 대회 시작부터 AWS 분들의 연기와 함께 상황극이 시작되었습니다. (눈치 없는 저는 5분쯤 지나서야 이게 상황극이란 걸 인지했습니다.. )
Unicorn.Rentals라는 회사의 CEO가 등장하여 CTO가 코로나로 인한 자가격리 중이라 서비스 대응을 제대로 하지 못한다는 비극을 전해줍니다. 저희는 모두 Unicorn.Rentals의 DevOps 엔지니어들로 CTO가 구축해놓은 시스템을 파악하고 운영해야 합니다. 이 서비스는 이미 고객들의 요청을 처리하고 있으며 트래픽은 더욱 늘어날 예정입니다. 4시간 동안 CTO의 도움 없이 빨리 현재 상황을 파악하고 수정하여 시스템을 안정적으로 운영해야 하는 것이 저희의 임무입니다.
조금 더 설명해 드리자면 저희 서비스는 하나의 API endpoint를 노출하고 있고 해당 API로 사용자들의 요청이 꾸준하게 들어오고 있습니다. API는 하나의 파라미터를 query string parameter로 받으며 응답으로는 파라미터에 대한 hash 값을 주고 있습니다. 저희가 얼마나 서비스를 잘 운영하고 있는지는 점수로 확인 할 수 있습니다. 요청을 더 빨리 처리할수록 높은 점수를 받고 요청을 제대로 처리하지 못하는 경우 점수가 차감됩니다. 또한 주기적으로 저희가 사용하고 있는 AWS 인프라 리소스에 대한 비용이 점수에서 차감됩니다.
따라서 대회의 목적은 최소의 비용으로 최고의 효용과 안정성을 갖춘 인프라를 구성하는 것입니다. 제공되는 스코어 보드 페이지를 통해 현재 참여한 팀들의 점수와 점수 trend를 실시간으로 확인할 수 있습니다.
진행 내용
게임이 시작되고 기존에 갖춰져 있던 시스템이 들어오는 요청을 잘 처리하는 덕분에 모든 팀의 점수가 조금씩 같이 오르기 시작했습니다. 저희는 우선 대회에서 제공되는 Runbook을 읽고 상황을 파악하고 여러 단서를 찾는 데 집중했습니다.
가장 첫 번째 눈에 들어온 건 query string parameter로 parameter가 넘어오고 같은 parameter의 경우 응답에 담기는 hash가 일정하다는 것이었습니다. 그래서 맨 처음 한 작업은 AWS의 CDN 서비스인 CloudFront를 이용하여 query string parameter 기반의 캐싱을 진행하는 것이었습니다. 저희가 제공하고 있는 API는 요청을 하나 처리하는데 4초 이상 걸리는 굉장히 오래 걸리는 API였기 때문에 캐싱이 큰 효과를 발휘할 것이라는 판단을 했습니다. 다만 같은 값이 얼마나 중복으로 요청될지는 몰랐지만 간단하게 할 수 있는 작업이었다 보니 바로 적용을 해뒀습니다. 캐시 히트가 되는 경우 EC2까지 요청이 전달되지도 않고 앞단에서 바로 클라이언트로 응답을 줄 수 있으니 가장 효과적인 캐싱 방법이라고 생각했습니다. CloudFront는 리멤버 커리어, 리멤버 커뮤니티, 커리어 채용공고 등 평소 리멤버 웹 사이트들이 모두 잘 사용하고 있는 서비스다 보니 어려움 없이 바로 적용할 수 있었습니다.
그다음으로는 지금 구성되어있는 아키텍처에 잘못된 부분은 없는지 확인했습니다. 불필요한 설정으로 추가 금액이 나가는 예도 있었고 사용되지 않는 지원들도 있어서 이를 모두 제거했습니다. 또한, VPC 설정을 보다 보니 사용 가능한 IP의 제한이 있어서 subnet도 바로 추가했습니다. 그 외 배포 과정에도 비효율적인 내용을 제거했습니다.
API의 처리 시간이 매우 길어서인지 제공되는 서비스 binary가 EC2 서버 한 대의 처리량이 명확해 보였습니다. 따라서 요청량에 따른 EC2 auto scaling이 필요하다고 판단했고 Request count per target 지표를 확인하기 위해 Classic Load Balancer를 Application Load Balancer로 변경했습니다.
요청량이 급격하게 변화하기도 하고 어떤 규칙을 보일지 몰라서 최대한 빠르게 대응하기 위하여 손토스케일링(손 auto scaling)을 진행했습니다. 이 부분이 꽤 큰 역할을 해줬는데요, 다른 팀들의 점수가 갑자기 급감할 때 저희는 플러스 점수를 유지하는 경우도 있었습니다. (인간이 기계보다 뛰어나다는 것을 보여줬습니다)
게임 규칙상 생성할 수 있는 EC2의 사양이 한 가지로 정해져 있었고 서비스가 EC2 인스턴스의 리소스를 충분히 활용하지 못하는 상황이었다 보니 더 효과적인 비용 절감을 위해서는 AWS의 container 서비스인 ECS를 이용해야겠다고 판단했습니다.
마치 약속이라도 한 듯 누가 시키지도 않았지만 자연스럽게 참여 인원의 절반은 ECS의 신규 아키텍처 기반의 설계를, 절반은 더 빠른 Auto Scaling을 통해 기존 시스템 운영을 맡았습니다.
ECS(Elastic Container Service)는 AWS에서 제공하는 컨테이너 오케스트레이션 서비스이며 어떻게 서버를 구성하냐에 따라 두 가지 방식으로 나뉩니다. 하나는 저희가 EC2를 직접 실행한 뒤 그 안에 실행되는 container들을 ECS에서 관리해주는 방식이고 다른 하나는 Fargate라고 부르는 serverless 방식입니다. Fargate는 쉽게 생각해서 AWS Lambda와 같은 개념이라고 보시면 됩니다. 처음에는 EC2 기반의 ECS를 구축하려고 시도했었는데 저희 모두 EC2 기반의 ECS를 구축한 경험이 없었어서 일부 설정에서 생각대로 잘 동작하지 않았습니다.
그러다가 중간에는 더 늦어지면 안 되겠다 싶어서 Fargate 기반의 ECS로 변경했습니다. Fargate의 경우 리멤버 커뮤니티 등 여러 서비스에서 이미 사용하고 있었기 때문에 손쉽게 구축할 수 있었습니다. Fargate로 아키텍처를 모두 이전한 뒤 점수가 많이 오르기 시작했습니다.

어느 정도 작업도 완료했고 안정적으로 오르는 점수에 만족하던 중에 갑자기 EC2 인스턴스가 종료되기 시작했습니다. 빠르게 돌아가는 상황이다 보니 “이상하네? 근데 뭐 누군가 실수했겠지”라고 생각할 수도 있었지만, 혹시 모를 문제를 대비하기 위하여 사용자 활동 감시 서비스인 CloudTrail에서 로그를 확인했습니다. 역시 저희의 실수가 아니라 Chaos Monkey가 AWS 리소스들을 조회하고 종료하는 것을 확인했습니다. 문제를 일으켜서 대응이 필요한 부분은 빠르게 대응을 했고 망가트리지 못하게 일부 설정은 조정해두었습니다.
Chaos Monkey는 Netflix에서 만든 Chaos Engineering을 위한 모의훈련 툴로 임의로 서버나 컨테이너를 종료시켰을 때도 서비스가 잘 동작하는지 확인하기 위한 목적으로 만들어졌습니다. 인스턴스 종료뿐만 아니라 AZ나 리전 전체를 셧다운 하는 Chaos Gorilla, Chaos Kong 등도 있습니다. Chaos Engineering에 대해 궁금하시다면 카오스 엔지니어링의 원칙을 읽어보시거나 YouTube에서 Netflix의 기술 발표 영상들을 참고해보시면 좋을 것 같습니다. 
Chaos Monkey뿐만 아니라 적은 내부에 있다고 Unicorn.Rentals 대표님이 뭔가 해보시겠다고 하는 게 문제를 발생시키는 경우도 있었습니다 
또한 후반으로 갈수록 트래픽이 급증했는데, 가장 처음에 도입했던 CloudFront가 효자 노릇을 톡톡히 해줬습니다. 중복된 parameter 요청이 많이 날라왔는지 대부분의 요청이 CloudFront 단에서 처리되고 끝났습니다.
어느덧 4시간이 지나버렸고 대회가 종료되었습니다. 이멤버리멤버 팀이 1등으로 게임을 끝냈습니다. 처음에는 중간 등수였지만 작업을 할 때마다 점수와 순위가 함께 오르기 시작했습니다.
후기
저희 모두 큰 기대를 갖고 참여했던 대회는 아니었습니다. 다들 워낙 바쁘다 보니 오랜만에 재미있게 놀다 오자라는 마음으로 참여했다가 점수가 잘 나오니 뒤로 갈수록 더 열심히 몰입했던 것 같습니다. 개인적으로는 방 탈출을 정말정말 좋아하는데 처음에 몰입을 위한 설정, 상황극, 연기, 다양한 함정 및 문제 등이 방 탈출과 비슷하여 훨씬 더 몰입할 수 있었습니다.
저희가 평소에 고민했던 부분을 해결하기 위한 아키텍처와 서비스를 그대로 적용되었다는 점이 만족스러웠고 손발이 착착 맞는 팀워크에 저희 모두 감탄했습니다. 누가 시키지 않았음에도 서로 역할 분담을 하며 업무를 나눠가고 긴박한 상황에서도 실시간으로 상황 공유 및 확인을 계속 진행하여 여러 명이 동시에 AWS 리소스를 수정하면서도 충돌 없이 해낼 수 있었습니다. 그리고 나중에 알게 된 사실이지만 대회에 참가한 다른 회사들이 국내에서 손꼽히는 IT 스타트업, 대기업들이었다고 합니다. 코로나만 아니었어도 네트워킹 시간을 가질 수 있었을 텐데 아쉽지만 이런 팀들이 모두 모여 대회를 진행했다는 것만으로도 충분히 재미있는 경험이었습니다.
관심 있으신 분들은 정말 재미있는 시간을 보내실 수 있을 것 같으니 나중에 대회가 열리면 꼭! 참여해보시길 추천드립니다.

🏆 AWS 대회에서 1등 했습니다!

시작하며
안녕하세요. 카카오엔터프라이즈 테크니컬라이팅팀의 Crystal(김유리)과 Sandy(차신영)입니다.
 
그 동안 테크니컬커뮤니케이션 팀에서는 테크니컬 라이팅 4대 원칙과 언어학 관점에서 기술문서 가독성 향상 전략 등 테크니컬 라이팅과 관련한 정석적인 주제를 다뤘었는데요. 며칠 전 개발자 한 분께서 "테크니컬 라이팅 교육을 받고 싶은데 시간은 없고.. 어떻게 하면 기술 문서를 잘 쓸 수 있을까요? 혹시 간단한 팁이 있을까요?" 라는 질문을 주셨습니다.
 
 생각해보면 개발자들이 많은 시간을 들여 테크니컬 라이팅을 심도있게 공부하기는 현실상 쉽지 않은 게 사실인데요. 그래서 오늘은 수 많은 테크니컬 라이팅의 이론과 팁 중에서도 기술문서 작성에 관심이 있으신 개발자 분들이라면 꼭 알아야 할 10가지 팁을 간추려 소개하겠습니다.
 
 
 
테크니컬 라이팅 10계명
• Tip 1. 필수 문장 성분 생략하지 않기
기술문서 초안을 리뷰하다 보면 간단한 문장이라도 필요한 문장 성분 특히 주어(~은/는/이/가), 필수적 부사어(~에, ~에게), 목적어(~을, ~를)가 생략되어 정확한 의미를 파악할 수 없는 경우를 많이 보게됩니다. 다음 예시를 살펴 볼까요?
원문에서의 문장은 겉보기에는 이상이 없어 보일 수 있습니다. 하지만 문장을 자세히 들여다 보면 주어, 필수적 부사어, 목적어가 생략되어 있음을 알 수 있습니다. 즉, 누가 누구에게 Recognizer.ExpectSpeech Instruction을 전송한다는 건지 Service Agent가 무엇을 수신한다는건지 정확히 알 수 없습니다. 바로 주어, 필수적 부사어, 목적어 등이 생략되어 있기 때문인데요. 특히 Request와 Response가 분명한 API 레퍼런스나 복잡한 순서를 설명하는 문장에서 이런 필수 문장 성분들이 생략되어 있다면 독자는 해당 기능을 쉽게 파악할 수 없게 됩니다.
 
기술문서가 아닌 다른 형태의 글에서는 주어와 서술어가 생략되어도 맥락상 큰 문제가 없을 수도 있지만, 기술문서에서는 행동 주체와 그 행동을 받는 주체, 목적어가 명확히 구분되어야 하기 때문에 주어(~은/는/이/가), 필수적 부사어(~에게), 목적어(~을/를) 등을 반드시 명시하는 것이 좋습니다. 
 
• Tip 2. 문장 성분의 호응 지키기
문장 안에는 여러 문장 구성 성분들이 존재하며 이들이 자연스럽게 호응될 때 좋은 문장이라고 할 수 있습니다. 특히 주어와 서술어, 수식어와 피수식어, 부사어와 서술어의 호응 관계에 주의하여 문장을 작성해야 하는데요. 만약 문장 성분들이 서로 호응하지 않으면 의미가 불분명하고 모호하게 전달될 수 있습니다. 
 
주어와 서술어
주어와 서술어의 호응은 주체-행위, 주체-상태, 주체-속성의 관계를 올바르게 표현하는 것입니다. 아래 예시를 보면 주체와 속성의 관계가 올바르게 표현되지 않은 것을 확인할 수 있습니다.
예시의 원문이 어색한 이유는 '이유'란 '어떠한 결론이나 결과에 이른 까닭이나 근거/구실이나 변명'을 의미하는 명사인데, 이 명사와 호응이 되지 않는 서술어가 나왔기 때문입니다. 따라서 주어와의 호응에 따라 '~이기 때문이다', '~이다', '~한 것이다' 등의 서술어를 사용해야 합니다.
 
수식어와 피수식어
수식어와 피수식어의 호응은 꾸미는 말과 꾸밈을 받는 말의 관계를 분명하게 표현하는 것입니다. 꾸미는 말의 대상이 명확하지 않으면 이또한 전달하고자 하는 의미가 모호해질 수 있는데요. 
 
원문에서 '복잡한'이 수식하는 대상이 '소프트웨어'인지 '설치과정'인지 불분명합니다. 만약 '복잡한'의 대상이 설치 과정일 경우, '복잡한'의 위치를 적절히 옮겨 명확한 문장으로 수정할 수 있습니다. 
 
부사어와 서술어
어떤 부사는 특정 표현과 호응할 때 자연스럽기 때문에 글을 쓸 때 부사어와 서술어의 호응에 유의해야 합니다. 예를 들면, '반드시'의 경우는 긍정의 서술어와 호응할 때 자연스러우며, '결코'나 '절대로'는 부정의 서술어와 호응할 때 자연스럽습니다.
'표준국어대사전'에서는 '절대로'를 '어떠한 경우에도 반드시'로 뜻풀이하고, '세상에 절대로 공짜라는 것은 없다./절대로 나쁜 일을 해서는 안 된다./그는 절대로 상대해서는 안 될 사람이다.'의 용례를 보여주고 있는데요. 이처럼 '절대로'는 주로 부정(-지 않다 등)을 나타내는 말과 호응하는 것이 자연스러우며, 긍정을 나타내는 서술어와 호응하고자 한다면 '틀림없이 꼭'이라는 뜻을 가진 '반드시'를 대신하여 사용하는 것이 자연스럽습니다.
 
• Tip 3. 조사 올바르게 사용하기
조사는 주로 명사에 붙어서 다른 말과의 관계를 나타내거나 특별한 뜻을 더해 주는 품사인데요. 조사는 문장에서 아주 작은 부분만을 차지하고 있지만, 내용을 모르는 독자가 꼼꼼히 읽다 보면 조사 때문에 의미 파악이 어려워지는 경우가 많습니다. 게다가 필요하지 않은 조사를 쓰면 문장이 길어지고 읽기 힘들어지기 때문에 없어도 이해하는데 문제가 없는 조사들은 과감히 생략해야 합니다. 
 
불필요한 조사 생략
SDK 다음에 굳이 '를'이라는 조사가 오지 않아도 이해하는데 문제가 없습니다. 이처럼 불필요한 조사가 들어가게 되면 문장의 전달력과 가독성이 떨어지므로 반드시 문장을 완성한 뒤 불필요한 조사가 들어가 있지는 않은지 확인을 하는 것이 좋습니다.  
 
영어 발음에 맞는 조사 사용
영단어 뒤에 조사를 사용할 때에는 영어 발음에 맞는 조사를 사용해야 합니다. 다음 예시에서 Writing(라이팅)의 발음에 맞는 조사는 '는'이 아닌 '은' 이므로 조사 변경이 필요합니다.
 
소괄호 앞에 오는 단어에 맞는 조사 사용
소괄호가 있는 단어에 조사를 사용할 때에는 소괄호 바로 앞에 오는 단어에 맞춰 조사를 사용합니다. 아래 예시에서 조사는 괄호 안이 아닌 괄호 앞에 위치한 Language(랭귀지)에 맞춰야 하므로 올바른 조사는 ‘는'이 됩니다. 
• Tip 4. 피동형/사동형 지양하기
영어식 문장에서는 무생물을 주어로 하여 피동형이나 사동형 표현이 우리말보다 일반적이지만, 우리말 표현에서는 이런 표현들이 어색할 때가 있습니다. 따라서 인물을 주어로 하여 자연스러운 우리말 표현이 가능한데도 무생물을 주어로 내세워 사동 표현이나 피동 표현으로 쓰는 경우는 지양해야 합니다. 기술문서에서 피동형/사동형 문장은 번역 투의 느낌이 강해지기 때문에 부자연스럽다는 느낌을 줄 수 있고, 특히 피동 표현은 책임 회피의 부정적 태도가 있어 의도한 것과 다르게 문장의 의미가 전달될 수 있습니다. 따라서 꼭 필요한 경우가 아니라면 피동형과 사동형은 지양해야 합니다. 
 
예시의 원문에서 '클릭되어야'는 불필요한 피동형 표현으로, 버튼은 사람이 주체가 되어 클릭하는 것이기 때문에 피동형 표현을 능동형으로 수정하면 더 자연스러운 문장이 됩니다. 
• Tip 5. 이중 부정 지양하기
표준국어대사전에 따르면 이중 부정이란 한 번 부정한 것을 다시 한 번 부정하여 긍정을 나타내는 것을 뜻합니다. 이중 부정을 쓰면 한 번 부정한 내용에 대해서 다시 또 부정해야 하기 때문에 문장이 불필요하게 복잡해질 수 있는데요. 이 경우, 독자가 문장을 읽고 이해하는 데 시간이 더 오래 걸리고 문장의 의미도 모호해질 수 있습니다. 따라서 기술문서에서는 가능한 이중부정 대신 긍정문을 사용하여 간결하고 명료한 표현을 사용하는 것이 바람직합니다. 
 
다음 예시를 보면, 원문은 휴게시간이 소정근로시간에 포함된다는 내용이지만 이중 부정을 사용하여 한 번 더 생각해야 정확한 의미를 파악할 수 있습니다. 기술문서에서 이중 부정은 지양해야 하므로 이중 부정을 긍정문으로 수정할 경우 내용을 훨씬 명확하게 알 수 있습니다.
• Tip 6. 명확한 표현 사용하기
기술 문서를 작성할 때에는 초급 개발자들도 문서를 쉽게 이해할 수 있도록 명확하고 구체적인 표현을 사용해야 합니다. 뜻 자체가 모호한 표현이나 여러 해석이 가능한 표현을 사용하면 작성자의 의도와 다르게 독자가 받아들일 수 있습니다. 따라서 기술 문서 작성 시 모든 독자에게 하나의 동일한 의미가 전달될 수 있도록 명확한 표현을 사용하여 작성해야 합니다. 
 
구체적인 수치 활용
어떤 정도에 대해 표현하는 문장에서 정확한 시간이나 양과 같은 수치를 "추상적으로 표현하면" 의미 전달이 모호해질 수 있습니다. '조금', '잠시', '많이', '꽤', '곧' 등과 같은 추상적인 표현을 사용해 ‘정도’를 나타내는 경우, 독자마다 다르게 생각하여 혼선을 빚을 수 있습니다. 따라서 어떤 정도를 표현해야 하는 경우, 수치를 활용하여 표현하면 정도를 구체적으로 명시할 수 있기에 의미가 보다 명확하게 전달될 수 있습니다.
 
예시의 '많은 시간'이란 표현도 사람마다 다르게 이해할 수 있고, 도대체 어느 정도의 시간이 필요한지 가늠하기 어렵습니다. 이러한 경우 아래 문장처럼 '시간/분/초'와 같은 시간단위를 활용하여 수치로 나타내면 보다 명확한 표현이 됩니다.
 
여러 해석이 가능한 표현 지양
우리가 일상적으로 사용하는 표현 중에는 의미가 정확하지 않고 여러 의미로 해석될 수 있는 표현들이 있습니다. 기술문서에서 이런 단어들을 그대로 사용하다 보면 독자에게 명확한 의미 전달이 어렵기때문에 이런 표현을 사용하지 않는 것이 좋습니다. 
위 예시에는 모호한 표현이 두 개나 포함되어 있는데요. 원문에 따르면 시스템상에서 주 52시간 근무 제한을 적용하는 설정에 대한 설명인데, 근무시간에 도대체 어떤 영향을 준다는 것인지 직관적으로 알 수 없습니다. '주 52시간 넘게'라는 표현도 52시간을 포함하는 것인지 아닌지가 불분명합니다. 수정문에서는 해당 설정이 최대 근무시간 설정에 정확히 어떤 영향을 주는지 알 수 있고, 주 52시간까지 포함해서 근무시간을 설정할 수 있다는 점을 더 명확히 전달할 수 있습니다.  
 
대상을 명확히 지칭
기술문서에서는 지시 대상을 명확하게 구분해 정보를 정확하게 전달해야 합니다. 예를 들어, 한 문서에서 두 종류의 서버가 언급되는 경우 단순히 서버라고 지칭하지 않고 어떤 서버인지 구체적으로 명시합니다.
예시에서는 어느 서버에서 요청을 받아서 고객사 서버로 전달하는지 파악하기 어렵습니다. 고객사 서버에서 온 요청을 다시 고객사 서버로 보내는 것인지, 아니면 다른 서버인지 정확히 명시되어 있지 않습니다. 따라서 대상을 명확히 지칭할 수 있도록 하는 것이 중요합니다.
• Tip 7. 순서와 목록 구분하기
문서를 작성하다 보면 순서를 설명하는 경우(순서가 있는 목록)와 단순히 목록을 나열하는 경우(순서가 없는 목록)가 발생합니다. 테크니컬라이팅을 접하지 않으신 분들이라면 순서가 있는 목록과 순서가 없는 목록을 숫자와 글머리 기호 등을 혼용하여 글을 작성하실 수도 있는데요. 테크니컬 라이팅에서는 순서가 있는 목록에는 숫자를 사용하며, 순서가 없는 목록에는 글머리 기호 또는 하이픈 등을 사용하는 것이 일반적입니다. 이 두 경우를 서로 혼용하게 되면 독자에게 혼란을 줄 수 있기 때문에, 순서가 있는 목록과 순서가 없는 목록을 구분하여 글을 작성하는 것이 좋습니다.
 
• Tip 8. 개조식 활용
기술 문서를 작성 할 때 대부분의 경우에 '~다'로 끝나는 서술식 문장을 사용하는 것이 일반적입니다. 하지만 테이블이나 간단한 안내 항목 등에서 '~다'의 종결 어미 대신 명사나 용언의 명사형(예: ~임, ~함)으로 문장을 끝내는 개조식과 글머리 기호 또는 하이픈 등을 적절히 사용하면 문서의 가독성을 높일 수 있습니다. 다음 예시에서 처럼 문장이 길게 서술되어 있어 내용을 파악하기 힘든 경우, 개조식 형태와 하이픈을 사용해 가독성을 개선할 수 있습니다.  
• Tip 9. 맞춤법/띄어쓰기 체크하기
며칠을 고생해서 만든 PPT 문서를 발표하려고 문서를 열었는데 오타를 발견해서 당황한 경험, 고객사로부터 전달받은 문서에 맞춤법 오류가 있어 문서에 대한 신뢰도가 떨어진 경험... 다들 한번 쯤은 있으실 텐데요. 
 
기술문서가 얼마나 잘 쓰여졌는지와는 상관없이 해당 문서에 맞춤법, 띄어쓰기, 오타 등의 오류가 있다면 해당 문서가 빛을 잃는건 한 순간입니다. 그래서 저희 팀에서도 문서 최종 릴리즈 시점에 이런 오류를 잡아내기 위해 몇 번의 리뷰 과정을 거치는데요. 다음과 같이 자주 틀리는 맞춤법을 공부해 두면 글을 쓸 때 도움이 될 수 있습니다.
 
 
하지만 단 시간에 모든 맞춤법이나 띄어쓰기 용법을 독파하는 것은 쉽지 않습니다. 또한 사람의 눈으로 이런 오류를 단시간에 모두 찾아내는 건 꽤 어려운 작업이기 때문에 저희 팀에서는 맞춤법 검사기를 보조 수단으로 사용하고 있습니다. 맞춤법 검사기를 사용하다보면 자연스럽게 내가 자주 틀리는 맞춤법이나 띄어쓰기가 무엇인지 파악하게 될 것이고, 결과적으로 이런 오류는 점차 줄어들게 될 것입니다. 맞춤법이나 띄어쓰기 용법을 공부하여 하나씩 적용해 보는 것도 좋지만, 이런 시간이 부족하다면 문서를 최종적으로 완성하기 전에 반드시 맞춤법 검사기를 사용해 보실 것을 추천드립니다.
 
• Tip 10. 외래어 표기 체크하기
맞춤법과 마찬가지로 자주 틀리기 쉬운 외래어도 알아두면 좋은데요. 특히 애플리케이션(어플리케이션 X), 비즈니스(비지니스 X) 처럼 회사 뿐만 아니라 일상적으로 사용하는 단어를 계속 잘못된 표기법으로 사용하고 있다면 조금 억울하지 않을까요? 모든 단어의 정확한 외래어 표기를 익히는건 어렵더라도, 적어도 업무 중 자주 사용하고 있는 외래어 표기는 한번쯤 눈여겨 보는 것을 추천드립니다. 이 밖에 외래어 표기는 국립국어원이 운영하는 한국어 어문 규범에서 확인할 수 있습니다.
 
 
마치며
지금까지 개발자들을 위한 테크니컬라이팅 10계명이라는 주제로 국문으로 기술 문서를 작성할 때 알아두면 좋은 팁들을 소개해 드렸는데요. 포스팅 길이를 염두에 두다 보니 기술 문서를 작성할 때 자주 틀리게 되는 내용 위주로 포스팅을 구성하게 되었습니다. 
 
이번 포스팅을 재미있게 읽으셨다면, 시중에 나와있는 테크니컬라이팅 서적들도 한 번 읽어보시는 것을 추천드립니다. 막연하게 테크니컬라이팅은 어렵다라고 생각하기 보다는 위에서 강조드린 팁들 부터 하나씩 실전에 적용해 보다 보면 문장에 대한 논리, 논리적 연결 관계, 가독성과 같은 주제에 자연스럽게 관심을 가지실 수 있을 것입니다. 개발자들에 있어 개발만큼이나 문서화의 중요성도 강조되고 있는 요즘, 오늘 포스팅이 작은 도움이 되면 좋겠습니다. 감사합니다.
 
 
  테크니컬 라이팅 관련 글 더보기  
     ✓ 목차의 중요성
     ✓ 기술 문서 작성 5단계
     ✓ 테크니컬 라이팅 4대 원칙 
     ✓ 기술 문서 쉽게 쓰기 지침
     ✓ 언어학 관점에서의 기술문서 가독성 향상 전략 
     ✓ 카카오 i 기술문서 사이트 여정, 그리고 벌써 한 달 
     ✓ Technical Writer에서 Technical Communicator로...  
     ✓ [KREW INSIDE] AI 서비스의 기술 문서를 책임지는 사람들, 테크니컬 라이터 
 
 
 
참고 문헌   
[1] 이공계 Technical Writing 가이드(북코리아)
[2] 웹 기획자가 알아야 할 서비스 글쓰기의 모든 것 (위키북스)
[3] 국립국어원 홈페이지
[4] 이공계는 글쓰기가 두렵다 (마이넌)
[5] 독서와 문법 II(지학사)
 
김유리(Crystal)
사용자의 입장에서 생각하고, 개발자와 원활한 소통을 할 수 있는 Communication Skill을 가진 Technical Communicator입니다. 카카오엔터프라이즈의 값진 기술들을 정확하고 명확하게 전달하고, 신뢰를 쌓을 수 있는 문서를 만들고자 합니다. 
차신영(Sandy)
산더미처럼 쌓여진 문서 정리, 새로운 문서화 도구 테스트, 그리고 구글링이 취미인 Technical Communicator입니다.

Seungho Kim

책

슬라이드

앱

글

기술 뉴스 #176 : 21-06-15

'노마드 코더'를 운영한 지 4년이 되었다 - 아우. 경쟁 너무 빡세.

🏆 AWS 대회에서 1등 했습니다!

개발자들을 위한 테크니컬 라이팅 10계명 #기술문서_작성법#개발자_글쓰기 #테크니컬라이터