인용 출처: 개발자의 글쓰기 (김철수 저, 위키북스)
개발자의 글쓰기 회고
개발자는 블로그, 개발 문서, 이메일, 보고서 등 글을 자주 쓴다. 글을 잘 쓰고 싶어 대학에서 강의도 수강하고 책도 찾아 읽어봤다. 하지만 여전히 명확한 답이 나오지 않았다. 그래서 무작정 블로그를 쓰기 시작했다. 쓰다 보면 늘지 않을까 했다. 그런데 어느 순간 블로그를 돌아보니 글이 엉망이었다.
문제
기획자나 관리자의 글쓰기에 논리력, 설득력, 실행력이 중요하다면, 개발자의 글쓰기에 정확성, 간결성, 가독성이 중요하다.
문장이 간결하지 않다. 불필요한 수식어와 접속사가 넘쳐난다. 개발 블로그는 정보 전달이 중요하다. 따라서 문장을 다듬는 방법을 알아야 했다. 그리고 말하고자 하는 내용이 정리되지 않았다. 가장 큰 문제였다. 의식의 흐름대로 글을 쓰다보니 내용이 중구난방이었다. 체계적으로 정보를 전달할 필요가 있었다.
마크다운 활용
마크다운은 글을 쉽게 작성할 수 있도록 도와주는 마크업 문법이다. 문법이 어렵지 않아 쉽게 익힐 수 있다. 무엇보다 정말 편하다. 자세한 내용은 "마크다운"을 참고하자.
글 구조화
비즈니스 문서에서 위치와 계층은 항상 붙어 다닌다. 위치만 있어서도 안 되고 계층만 있어서도 안 된다. 글을 쓸 때는 항상 위계가 잘 드러나게 글을 쓰고 표현해야 한다.
마크다운은 #을 통해 쉽게 글을 구조화할 수 있다. 글의 챕터와 소제목이 분명하게 구분되어야 한다. 그래야 현재 문단이 어떤 이야기를 하는지 쉽게 파악할 수 있다. 마크다운에서 #는 h1, ##은 h2, ###은 h3와 같이 # 개수에 따라 계층이 나뉜다. 다만, 플랫폼에 따라 h2부터 시작하거나 h3부터 시작할 수 있다. (글 제목이 h1이기 때문에)
글 쓰기에 집중
서식을 쉽게 수정할 수 있기 때문에 글쓰기에 집중할 수 있다. # > [] - 등 기호로 제목, 인용, 체크박스, 글머리 기호와 같은 스타일을 쉽게 표현할 수 있다. 일종의 단축키 느낌이다.
게다가 어느 플랫폼에서 작성하든 서식이 유지된다. 글을 옮길 때 서식이 깨질 걱정은 없다. 당연히 서식을 수정하기 위해 시간을 낭비하지 않아도 된다.
개발 생태계
Github, Notion, Velog 등 여러 툴에서 사용한다. 개발자에게 마크다운은 사실상 필수다. 최소한 Github README는 쓸 줄 알아야 하니 간단한 문법은 익히는 걸 추천한다.
글 구조화
키워드 나열
쓰고 싶은 이야기를 체크리스트로 만든다. 브레인 스토밍을 하는 과정이다. 글을 작성하면서 키워드를 찾으면 내용이 산으로 간다. 먼저 쓰고 싶은 내용을 충분히 고민하는 과정이 필요하다. 체크리스트로 작성하는 이유는 다시 확인하기 위해서다. 글을 작성한 후 빠진 내용은 없는지 확인할 때 사용한다.
소제목과 핵심 문장
키워드를 묶어 여러 소제목으로 나눈다. 참고로 마크다운에서 #은 제목, >은 인용 기호다.
# 개발자의 글쓰기 회고
- 개발자는 블로그, 개발 문서, 이메일, 보고서 등 글을 자주 쓴다.
- 어느 순간 블로그를 돌아보니 글이 엉망이었다.
## 문제
> 기획자나 관리자의 글쓰기에 논리력, 설득력, 실행력이 중요하다면,
개발자의 글쓰기에 정확성, 간결성, 가독성이 중요하다.
>
- 문장이 간결하지 않다.
- 말하고자하는 내용이 정리되지 않았다.
# 마크다운 활용
## 글 구조화
> 비즈니스 문서에서 위치와 계층은 항상 붙어 다닌다.
위치만 있어서도 안 되고 계층만 있어서도 안 된다.
글을 쓸 때는 항상 위계가 잘 드러나게 글을 쓰고 표현해야 한다.
>
## 글쓰기에 집중
- 서식을 쉽게 수정할 수 있기 때문에 글쓰기에 집중할 수 있다.
- 마크다운은 어느 플랫폼에서 작성하든 서식이 유지된다.
(생략)현재 글을 작성하기 전 구조화한 개요다. 우선 #으로 소제목을 작성했다. 글이 어떻게 흘러가는지 정리하는 과정이다. 개요가 정리됐다면 각 소제목마다 내용을 요약해 완전한 문장으로 작성했다. 이 문장이 문단 첫 문장이 된다.
문장을 쉽게 쓰려면 이처럼 간단한 문장 구조로 핵심만 말한 뒤, 필요에 따라 부가 설명을 하면 된다.
이렇게 하면 글을 두괄식으로 작성할 수밖에 없어진다. 핵심을 먼저 말하면 글을 이해하기 쉬워진다. 여기까지 작성했다면 이제 문장을 이어나가면 된다. 하지 못한 설명을 이어 붙여 글을 풍성하게 만든다.
불필요한 표현 다듬기
실제 블로그 글을 다듬으며 나타난 실수다. "내 문장이 그렇게 이상한가요? (김정선 저)"를 참고했다.
- 개인적인 스타일이 반영됐다. 평가 기준은 "실질적으로 사용 가능한가"이다.
- 필자의 스타일을 반영했다. 평가 기준은 “실제 사용 가능한가”이다.
- 최종적으로 나온 출력값
- 최종 출력
- 얼굴의 랜드마크
- 얼굴 랜드마크
- 딥러닝은 인공신경망을 이용한 것이다.
- 딥러닝은 인공신경망을 이용한다.
- 결과가 도출됐다.
- 결과를 도출했다.
- 함수를 통해 계산된다.
- 함수로 계산한다.
- 행렬에 대한 이해가 필요하다.
- 행렬을 이해해야 한다.
- 미분을 한다.
- 미분한다.
- 데코레이터를 사용하고 있는 함수
- 데코레이터를 사용하는 함수
- 머신러닝 기법 중 하나로
- 머신러닝 기법으로
- CNN의 경우 느릴 수 있다.
- CNN은 느릴 수 있다.
- 값을 최소할 수 있는 방법을 찾는다.
- 값을 최소화하는 방법을 찾는다.
- 값이 작아지는 것을 볼 수 있다.
- 값이 작아진다.
- 태그들을 찾아야 한다.
- 태그를 찾아야 한다.
없어도 되지만 습관적으로 사용한 표현이다.
모든 문장은 다 이상합니다. 모든 사람이 다 이상한 것처럼 말이죠. 제가 하는 일은 다만 그 이상한 문장들이 규칙적으로 일관되게 이상하도록 다듬는 것일 뿐, 그걸 정상으로 되돌리는 게 아닙니다.
- 내 문장이 그렇게 이상한가요?
수정한 문장이 좋은 문장인지 필자는 모른다. 하지만 글이 전체적으로 간결해졌다. 이상한 문장일 수 있지만 그래도 일관되게 이상해졌다.
참고 자료: 내가 쓴 글 스스로 다듬는 법 - brunch
정리
- 키워드 나열
- 소제목으로 구조화
- 소제목을 한 문장으로 요약
- 글 이어 붙이기
- 불필요한 표현 다듬기
글 잘 쓰고 싶다.