📝 김철수님의 '개발자의 글쓰기'를 읽고 정리한 글입니다. 문제가 될 경우 삭제 조치하도록 하겠습니다.

0. 들어가며

나는 개발에 있어 기록이란 팀원들 혹은 미래의 자신 그리고 내가 도움을 받았던 글들의 작성자 에게 돌아가고 더 나아가서는 내 지식을 얻고 싶은 독자들에게 많은 도움이 된다고 생각한다.

그래서 최근에 글쓰기 활동을 나름 열심히 했다 하지만 글을 쓰고 여러 번 수정해도 내가 생각하는 글을 잘 쓰는 기준에 들지 못했다.

물론 처음에 작성했던 글과 최근에 작성한 글을 비교하면 큰 발전을 했지만 내가 생각하는 글을 잘 쓰는 기준에 들기 위해 시간과 여러 시행착오를 들이기 보다 이미 글을 잘 쓰고 검증된 사람에게 지식을 얻고 실천하는 것이 안전하고 빠르게 갈 수 있는 이정표라고 생각해 개발자의 글쓰기 라는 책을 펴게 되었다.

💡 내가 생각하는 글을 잘 쓰는 기준

• 나를 포함해서 누구나 쉽게 이해해야 한다.
• 나를 포함해서 누구나 재미있어야 한다.
• 독자가 얻어 가는 게 있어야 한다.
• 자기만의 생각을 녹여야 한다.

책을 읽기 전에는 이러한 나만의 기준이 있었지만 읽고 실천하고 적용하면 위의 기준을 충족함과 동시에 다른 것들을 더 발전시킬 수 있다고 생각된다.

철봉 매달리기 1초도 못한 내가 이제는 풀업 10개는 쉽게 하는 것처럼 꾸준함과 점진적 과부하의 중요성을 알게되어 운동 이외에도 이번의 글쓰기와 같이 내가 하고자 하는 모든 것에 적용해 보려고 한다.
현재 자신이 못하는 것을 부끄러워서 안 하는 것보다 꾸준히 하면 향상될 것을 알고서도 안 하면 그것이 바보이며 부끄러운 것이라고 생각하기 때문이다.

아무튼 왜 그 많은 글쓰기 가이드 책 중에 개발자의 글쓰기를 고른 이유는 심플하다. 책 표지의 문구가 내가 평소에 필요성을 느낀 키워드들만 있었기 때문이다.

💡 변수 네이밍, 릴리스 노트, 장애 보고서, 기술 블로그 고민 끝

변수 네이밍은 개발자에게 있어 평생 숙제와 같은 것이고 릴리스 노트와 장애 보고서, 기술 블로그는 여러 사이드 프로젝트를 경험하면서 필요성을 느끼고 있었기 때문이다.

1. 프롤로그 개발자의 글쓰기는 달라야 한다.

저자는 나무꾼 이야기를 예로 학습자, 개발자가 요약한 글을 보여주면서 독자나 작성자에 따라 글 쓰는 방식이 다르며 독자가 평가하는 잘 쓰는 기준도 달라진다고 한다.

그러면서 개발자는 정확성, 간결성 가독성이 글 쓰는 데에 중요하다고 한다.

하지만 정확성을 높이면 간결성과 가독성이 내려가고 간결성을 높이면 정확성과 가독성 내려가며 가독성을 높이면 간결성과 정확성 내려간다고 한다.

이에 동의한다. 이 3가지 중 1개를 포기하기 싫고 다 잡고 싶어 글을 계속해서 수정하지만 항상 어려웠다. 앞에서 나무꾼 이야기로 예를 든 것처럼 나는 독자가 누구며 작성자가 추구하는 거에 따라 선택과 집중을 하면 된다고 이해했다.

2. 1장 개발자가 알아야 할 글쓰기 기본

2.1 문장과 단락을 구조화하는 법

책에서 서술한 대로 내가 문장을 만들어 봤다.

문장을 구조화하기 전

React는 제어 흐름의 권한이 개발자에게 있기 때문에 프레임워크가 아닌 라이브러리이다.

구조화 후

React는 라이브러리이다. 제어 흐름 권한이 개발자에게 있기 때문이다.

React 개발자라면 React는 라이브러리이다 라는 문장으로만 글을 이해할 수 있을 것이며 React 개발자가 아닌 사람들은 제어 흐름 권한이 개발자에게 있기 때문이다. 라는 부가 설명을 보면 이해할 수 있다.

즉 주어를 앞으로 빼서 간단한 문장 구조로 핵심만 말한 뒤 독자 성격에 따라서 부가 설명을 하면 된다.

2.2 서술식, 개조식, 도식의 차이

서술식

• ~다로 끝나는 완전한 문장으로 구성된 글
• 설명하거나 논증할 때 주로 사용
• 소설이나 신문 기사처럼 개발 가이드 문서에 사용

개조식

• 신문의 헤드라인
• 여러 사항 나열
• 릴리스 문서나 장애 보고서에 사용
• 글머리 기호 필수

도식

• 상태를 그림이나 서식으로 표기
• 행과 열로 이루어진 표

서술식에서 여러 사항이 유사한 패턴으로 반복될 때는 개조식으로 작성하는 게 좋다. 하지만 개조식에는 중복과 누락이 있을 수 있는데 더 디테일하게 작성하고 싶다면 도식으로 작성하면 된다.

즉 줄거리가 있는 설명이나 이야기이면 서술식, 여러 가지 종류의 항목과 내용이 반복되고 강조하고 싶으면 개조식, 각 항목이나 사항의 관계를 명확히 규정하고 싶다면 도식이다.

위계의 중요성도 언급했다.

💡 비즈니스 문서에는 위계가 있어야 한다. 위계가 없으면 문서가 아닌 소설이 된다.

2.2 쉽게 쓰는 띄어쓰기와 문장 부호

여기서는 띄어쓰기에 작은 팁을 주며 띄어쓰기에 너무 스트레스 받지 말라고 한다.

그리고 비즈니스 세계에서는 띄어쓰기 없이 생각을 전달하고 의미를 이해할 수 있어서 띄어쓰기가 중요하지 않다고 한다.

다만 아래와 같은 상황은 예외다

• 책 출간
• 발표 슬라이드 제작

저자는 위와 같이 예와 상황과 블로그를 쓸 때에는 맞춤법 검사기로 교정하면 충분하다고 한다.

말과 글은 시대에 따라 바뀌며 특히 한글은 띄어쓰기가 어려운 편이어서 중요하지 않다고 한 것 같고 맞춤법 검사기와 같은 툴이 너무 잘 되어 있어서 그를 이용하라는 것에는 저자의 말에 동의한다.

하지만 평소 글을 쓸 때 올바르게 작성하는 습관을 들이다 보면 나중에는 굳이 맞춤법 검사기를 사용하지 않아도 되기에 시간도 많이 절약되고 해당 툴이 없어질 때 대비할 수 있을 것이다.

2.3 큰따옴표, 작은따옴표

비즈니스 문서에서 따옴표의 용도

큰따옴표

책의 제목이나 신문 이름을 나타낼 때는 " " 큰따옴표를 사용

• 이번에 출간된 “개발자 글쓰기”를 참고했음
• 이 건은 “한겨례신문”의 기사를 토대로 작성했음

작은따옴표

소제목이나 예술 작품의 제목, 상호, 법률, 규정 등 그리고 강조와 규정에는 ' ' 작은따옴표를 사용

• 이번 프로젝트는 ‘코틀린’를 사용했음
• 이번 릴리스는 ‘개인정보 보호법’을 준수함
• 중요한 것은 ‘창의’가 아닌 ‘열정’
• ‘원인 분석’을 철저히 해야 함

2.3 영어 단어 선택과 외래어 표기법

• HTML에서 show로 레이어를 보여줬다면 hide로 감춰야 한다.
• hide 대신 invisible을 쓰면 안 된다. invisible의 반대말은 visible이기 때문

이와 같이 비슷한 듯 다른 단어가 많다 이러한 정확한 단어를 쓰는 것이 중요하다

하지만 팀원끼리 일관적이고 개연적인 합의만 되어 있다면 release를 릴리즈, Pythone을 파이썬으로 읽게 된 것처럼 정확한 단어는 그다지 상관없다고 한다.