[개발자의 글쓰기] 글의 종류별로 목차 잡는 법

pIutos 2022. 10. 28. 15:55

서론

"개발자를 위한 글쓰기" 책을 읽는 중 책의 [글의 종류별로 목차 잡는 법]에 대한 내용이 개발자가 글을 쓸 때 도움이 될 것 같은 내용이어서 요약하여 글로 남겨놓으려 한다.

'저'는 직접 경험한 것을 쓴 것으로, 개발 과정과 결과를 쓴 개발기가 여기에 해당한다. 저에 해당하는 글쓰기 예시는 다음과 같다.

개발기를 쓸 때는 목차를 잘 구성해야 한다. 개발을 하는 과정에서 최종적으로 성공한 루트와 중간에 실패한 루트를 구별하는것이 중요하다. 성공한 루트를 기준으로 목차를 잡고, 실패한 루트는 최종루트 다음에 문제해결이나 팁으로 정리해 덧붙인다.

책에서 소개한 예문의 목차를 정리하면 다음과 같다.

목차를 정리했다면 본문부터 쓰는것이 하나의 팁이다. 개발자가 가장 잘 쓸 수 있는 내용이 본문이기 때문이다. 그렇게 해서 본문을 쓰고 나면 맺음말을 쓰고, 머리말은 맨 마지막에 간략하게 떠오를 때마다 적는 것이 좋을 것이다.

'술'은 어떤 것을 분석해서 의미를 풀이하고 해석한 것이다. 개발에서는 새로운 기술을 자세히 설명한것이나 비슷한 용어를 비교해 풀이한 것, 에러 해결 방법 등이 술에 속한다. 술에 해당하는 글쓰기 예시는 다음과 같다.

책에서 제시한 예문은 GET과 POST의 차이인데, 이 예문의 목차를 정리하면 다음과 같다.

이 목차를 잘 보면 실제로 개발자가 쓴 글은 4장 뿐이다. 나머지는 참조한 HTTP 프로토콜의 문서를 정리한 것이다. 이렇게 원전의 내용을 먼저 쓰고 비교한 내용을 자기 생각으로 이론적으로 펼쳐 정리할 수 있다.

또 원전의 내용을 직접 실험해 비교한 뒤 그 내용을 정리해서 풀이할 수도 있다.

'편'은 산만하고 복잡한 자료를 편집해 질서를 부여한 것이다. 보통 시간 순서로 일어난 일이나 해야할 일을 쓴 것을 통칭하기도 한다. 개발에서는 프로그램 설치나 설정 순서, 개발 방법, 튜토리얼, 개발자 컨퍼런스 후기 같은 것이 여기에 해당한다.

편에 해당하는 글쓰기 예시는 다음과 같다.

글을 쓸 때는 한 일을 먼저 시간 순서로 적은 다음, 내용을 다 적는다. 그리고 단계를 만들고 묶은 뒤 하위 내용을 간략히 요약한다. 이렇게 쓴다면 아래 예시와 같이 글을 쓸 수 있다.

Git과 GitHub를 활용한 협업 공간으로 개발 시작하기
- Git저장소 만들기
- GitHub에 이슈 등록하기
Node.js와 Yarn으로 개발 환경 설정하기
- Node.js와 npm, yarn
- Node.js와 yarn 설치
- 프로젝트 생성
- package.json파일과 패키지 관리
- ...
Jest로 테스트 환경 설정하기
- 테스트 코드 작성
- Jest 설치
- 구현 코드 작성
- 테스트를 통한 구현 코드 수정
- 테스트 환경 공유
Travis CI를 활용해 리뷰 환경 개선하기
- Travis Ci를 활용한 테스트 자동화
- 애플리케이션의 설정 정보 관리
- Node.js 버전 유지
마치며

만약 글쓰기에 능숙하지 않다면 처음부터 구조를 생각하지 말고 본인이 한 일 등을 쭉 나열하고 그 내용부터 쓴 다음, 각 단계로 묶어 구조화하는것이 팁이 될 수 있다.

'집'은 여러 사람의 견해나 흩어진 자료를 한데 모아 정리하는 것이다. 내용을 많이 쓰기보단 핵심만 간결하게 정리하는 것이 좋고, 글 전체가 길지 않고 내용이 각각 나열 되어있다. 기술 블로그에서는 명령어 모음, 팁, ~가지 규칙 같은 것이 여기에 해당한다.

집에 해당하는 글쓰기 예시는 다음과 같다.

반드시 다른 여러 사람의 견해나 자료를 모아야 하는 것은 아니며 본인의 경험에서 터득한 것을 핵심만 정리해 나열하는것도 '집'이 될 수 있다.