사내 기술블로그에 기고한 글 중에 하나입니다.

사내 블로그 링크 : 개발자의 글쓰기는 다르다

개발자의 글쓰기는 다르다.

글이나 문서를 쓰며, 신경 썼던 부분 그리고 어떻게 하면 더 글을 잘 쓸 수 있을까에 대해 공부한 내용에 대해 공유합니다. 너무 자세하게 설명하면 내용이 길어질 것 같아 핵심만 작성합니다.

글쓰기는 중요하다.

신입 입사자 혹은 다른 팀에서 어떤 정보를 확인할 때는 문서를 확인합니다. 팀이나 비즈니스를 파악할 때 가장 중요한 요소 중 하나가 문서이고, 문서가 없다면 하나하나 다 물어봐야 하는 상황이 오게 되는데 이는 서로에게 힘든 상황이 발생할 수도 있습니다. 또한 이러한 문서가 관리가 안된다면, 결국 히스토리가 끊겨 회사의 서비스가 굴러가는데 문제가 발생할 수밖에 없습니다.

이러한 문제를 막기 위해서 문서화가 중요하고, 문서화 또한 개발자로서 보여줄 수 있는 하나의 가치라고 생각합니다. 다만, 많은 개발자들에게 글쓰기가 습관화되는 것이 어렵고, 개발보다 우선순위에서 밀린다고 생각하는 경우가 많습니다.

개발자의 글쓰기도 중요한 소양 중 하나다.

대개 개발자라면 한번쯤 변수명, 함수명에 대한 네이밍을 반드시 고민해봅니다. 어떻게 하면 다른 사람들이 봤을 때 이해하기 쉽도록 이름을 지을 수 있을까에 대한 고민을 가져본 사람이 많을 것입니다. 네이밍은 개발에서 언제나 고민되는 문제이고, 네이밍 또한 글쓰기 소양 중 하나입니다. 이처럼 글쓰기는 뗄 수 없는 관계입니다.

이름을 정할 때는 어떤 기능을 하는지, 비즈니스 케이스도 잘 표현해야 하고, 다른 사람들이 봤을 때 이해가 잘되게도 해야 합니다. 이러한 고민은 끊임없이 계속됩니다. 꾸준하게 콘퍼런스에서 네이밍 컨벤션에 대한 이야기가 나오는 이유도, 비슷한 이유라고 생각합니다.

좋은 이름을 정하는 방법

대부분의 경우, 이름 짓기는 창조이 영역이 아닌 조합의 영역입니다. 따라서 어떤 식으로 언어를 조합하는지가 이름을 잘 짓는지에 대한 방법입니다. 개발자의 글쓰기라는 책에서는 좋은 이름인지 확인하는 다섯 가지 기준을 명시하는데 이를 SMART라고 합니다.

easy to Search: 검색하기 쉽게
easy to Mix: 조합하기 쉽게
easy to Agree: 수긍하기 쉽게
easy to Remember: 기억하기 쉽게
easy to Type: 입력하기 쉽게

이름을 지었을 때, 이 규칙에 맞는가에 대해 한번 더 생각해보면 좋은 이름을 지을 때 도움이 될 것 같습니다.

비즈니스 규칙을 정의해서 룰을 만들자

약어에 대한 기준은 보편성입니다. 따라서 회사에서 사용하는 비즈니스 용어나 단어의 경우에는 대문자로 사용해도 됩니다. 다만 이에 대한 합의가 필요합니다. github wiki나 wiki에서 이러한 비지니스 용어를 명시하는 것도 하나의 방법입니다.

언어도 개발 실력이다.

개발을 할 때, 어학 사전을 켜고 개발하는 경우도 종종 볼 수 있습니다. 이러한 코드의 네이밍 컨벤션은 영어 표기법을 상속받았기 때문에 영어에 대한 중요가 큽니다. 중요한 단어가 앞에 오는 등의 이유나, 고유 명사를 대문자로 쓰는 이유가 대표적인 이유입니다.

노스캐롤라이나 주립 대학교의 크리스 파닌 교수의 연구결과를 보면 프로그래머가 이메일이나 다른 동료들 때문에 업무를 중단한다면, 생산성에 악영향을 미친다는 결론을 얻을 결과가 있습니다. 코딩을 작성하다는 도중에 중단이 되면 다시 그 업무로 돌아가는데 약 15분 정도가 걸리며, 1분 이내로 다시 일을 시작하는 경우는 10% 정도밖에 되지 않습니다. 이러한 비슷한 방향으로 단어를 검색하기 위해 웹브라우저를 켜고, 단어를 만드는 과정은 업무 효율이 내려가는 이유 중 하나입니다.

영어 단어도 미묘하게 의미가 다릅니다. change는 내용을 바꿀 때, modify는 오류를 수정할 때, revise는 기존에 없던 새로운 정보나 아이디어를 붙일 때 적합합니다. 다만 이러한 부분은 영어 실력의 차이가 있기 때문에 기존에 먼저 협의를 하는 과정도 필요합니다.

외래어 표현 등도 동일하게 사용하는 것이 중요합니다. 좋은 방법 중 하나는 국립 국어원 외래어 표기 용례를 찾는 것입니다.

협업에서 글쓰기는 더 중요하다.

PR과 Issue 에 대해서 가이드를 만들자.

많은 회사에서 github 로 프로젝트를 관리하는데, PR Template 을 사용하면 업무 효율을 높일 수 있습니다. 많은 회사에서 이미 사용을 하고 있으며, 작업자가 한 번 더 내용을 요약하면서 작업자는 내용을 정리할 수 있고, 이를 보는 리뷰어들은 내용을 이해하고 어디를 중점적으로 보아야 할지 알 수 있습니다. code review 할 때, 리뷰어들이 시간을 더 효율적으로 쓸 수 있고 팀 효율을 높이는데 중요한 방법입니다.

저희 Seller 팀에서는 다음의 template을 만들어 사용하고 있습니다.

[Feature / BugFix 등등] 변경점 요약

- What. 무엇을 바꿨는가
- How. 어떻게 바꿨는가
- (Optional) 주의할 사항, 신경쓸 사항
  - ex) client 측에서 사용하는 api 응답값 변경
- (Otpional) 참고사항
  - ex) wiki, jira link
  - ex) 관련 reference

팀마다 사용하는 규칙이 다르겠지만, 협의를 통해서 함께 협업을 하는 것이 좋습니다. 다만 일이 일을 만들지 않도록 이를 중간에서 조절하는 부분도 필요합니다.

팀에서 누군가는 글을 써야합니다.

글을 잘 쓰는 개발자가 팀에 있으면 편합니다. 회의나 다른 내용을 정리할 때, 이를 글로 작성해서 함께 공유하면 서로의 이해를 맞출 수 있습니다. 이러한 부분을 누군가 작성하지 않는다면, 이해하는 부분이 다를 수 있고 결국에 나중 시점에 이를 알게 되는 문제가 발생할 수 있습니다. 개발자는 이과에 가깝지만, 문과적인 소양도 필요합니다. 글을 읽기 싫어한다면 수많은 공식 문서와 개발 책들에 질릴 수도 있습니다.

글 쓰기의 습관화

제가 주로 사용하는 방법은 우선적으로 들리는 대로 내용을 적고, 이후에 묶어서 분류화하는 방법을 사용합니다. 이를 좀 더 자세하게 설명하면 다음의 전략으로 글을 분류할 수 있습니다.

구분	내용	종류
저	직접 경험하고 실험한 과정이나 결과	개발기, 도입기, 적용기
술	어떤 것을 분석하여 의미를 풀이하고 해석한 것	기술 소개, 용어 분석, 에러 해결 방법 등
편	산만하고 복잡한 자료를 편집해 질서를 부여한 것	프로그램 설치/설정 방법, 튜토리얼, 세미나 후기, 책 리뷰
집	여러 사람의 견해나 흩어진 자료를 한데 모아 정리한 것	명령어 모음, 팁. OO가지 규칙

글에 대한 종류에 대해 다르지만 목적에 따라 다르게 구별할 수 있습니다. 이와 같은 경우, 목적에 따라서 글의 스타일이 달라집니다.

개발자의 글쓰기는 다른 사람과 다르다.

테크니컬 라이팅

테크니컬 라이터는 사용자가 제품을 쉽게 사용할 수 있게 돕거나, 위험한 상황에 미리 대비할 수 있게 알려주거나, 문제가 생겼을 때 해결하는 방법을 가이드하는 문서를 쓰는 사람입니다.

최근에는 테크니컬 라이팅에 대한 중요도가 높아지는 추세입니다. 많은 회사에서 테크니컬 라이팅에 대한 교육을 실시하고 있고 테크니컬 라이터라는 직업을 가지신 분들도 많습니다. 이처럼 기술적인 글을 특정 독자에게 정확하고 명확하게 전달하기 위해 프로세스를 잘 사용하는 것이 중요합니다. 전문적인 테크니컬 라이터 정도로 글을 잘 쓸 필요는 없지만 어느 정도 쓸 수 있다면 이는 남들과 다른 하나의 차별점이 됩니다.

개발자의 글쓰기는 계층적이다.

개발자의 글쓰기의 핵심은 정확성, 간결성, 가독성입니다. 일반적으로 개발자가 쓰는 글은 소설이나 수필이 아닙니다. 대부분의 비즈니스 글은 계층적 구조를 유지하고 있으며, 비즈니스 글은 위계가 있어야 합니다.

ㅁㅁㅁ 서비스 업그레이드 결과

- 업그레이드 특징은 3가지 입니다.
  - 새로운 기능 추가
  - 버그없는 안정성 확보
  - 인공지능 도입

- 업그레이드 과정은 3단계입니다
  - 1단계 - ...

이러한 식으로 적어야지 다른 사람들이 봤을 때, 눈에 잘 읽히며 이해하기가 편합니다.

다른 사람들에게 설명하는 기술도 중요합니다.

글은 자신이 보기 쉽게 적기도 하지만, 다른 사람들이 보는 부분도 중요합니다. 따라서 이를 잘 표현하는 것도 중요합니다. 예를 들어 장애 발생 시, 다음과 같이 글을 쓴다면 정확한 문제를 몰라 질문을 하는 경우가 추가적으로 발생합니다.

서버 행아웃 상태로 인한 로그인 장애 발생(10:00 ~ 10:30)

하지만 이를, 좀 더 자세하고 위계가 있게 작성한다면 이를 보고 받는 사람이 봤을 때 내용 이해가 편합니다.

제목 : ㅁㅁㅁ 서버 지연으로 인한 로그인 불가 상황

- 장애 내용 : 일부 사용자 로그인 불가 (21-05-01 10:00 ~ 10:30)
- 장애 영향 : 사용자 접속으로 인한 다른 서비스 사용 불가 (로그인 실패 수 : XXXX)
- 장애 원인 : 특정 서버의 과부하 발생 이후, 서버 행아웃 상황 발생
- 조치 상황 : 서버 재시작
- 조치 결과 : 정상적으로 로그인 가능
- 핵심 원인
  - AA 이벤트로 인해 트래픽 몰림.
  - 서버의 XXX 병목 현상 발생
- 향후 대책
  - 서버 증설
  - 병목 발생하는 부분 수정 및 모니터링 자동화

마찬가지로 운영 반영 시에도 잘 설명하는 것이 좋습니다. 다만 사용자 입장을 위해 너무 딱딱하게 풀지 않아도 됩니다. 아래는 이러한 예시입니다.

개발자는 기획도 할 수 있어야 한다.

필요하다면 개발자는 기획도 할 수 있어야 합니다. 많은 경우, 기획자가 PRD(제품 요구사항 정의서)를 개발자에게 제공하면서 개발이 시작됩니다. 그러나 기술적인 문제에 대해서 이를 제안을 하고 설득을 하려면 기획자만큼 꼼꼼하게 작성할 필요가 없더라도 이야기를 할 수 있어야 합니다. 이때 "책, 기획의 신"에서는 핵심 기술을 다음으로 서술합니다.

Why → 이 기획의 목적
What → 기획안의 본론, 발견한 문제에 대한 해결책이 구체화되는 단계
How → 세부적인 실행 계획을 제시하는 단계

개발자가 보는 문제의 시각과, 기획자가 보는 문제의 시각은 다릅니다. 이러한 시각을 맞춰 방향성을 서로 맞춘다면, 업무 효율도 좋아지고 좋은 업무 평가도 따라올 것이라고 생각합니다.

마무리.

글을 잘 쓰는 사람들은 많습니다. 글을 잘 쓰는 개발자 또한 많습니다. 저 또한 이러한 강점을 가지기 위해 여러 책을 보며 공부를 했었던 내용을 요약하여 작성했습니다. 좋은 글쓰기를 통해 더 나은 서비스, 더 좋은 팀을 만드는 개발자가 많아지기를 바라며 글을 마치겠습니다.

출처

책 “개발자의 글쓰기”
책 “프로그래머의 뇌”
책 “IT 개발자의 영어 필살기”
책 “기획의 신”
기술 문서 작성 5단계, https://tech.kakaoenterprise.com/65
How to write a PRD, https://omareduardo.com/product-management/how-to-write-a-prd/

# Tech Writing

[Dev] 개발자의 글쓰기는 다르다