개발자의 효율적인 문서 작성법 (작성 중)

이중민님의 동명 강의 내용을 기록한 것입니다.

왜 글쓰기를 해야 하는가?

• 언제나 검색에 의존할 수는 없다. 기록을 남기고 그것을 찾아보는 것이 빠를 때도 많다.
• 사수는 대부분 업무 처리하느라 바쁜 사람이므로 처음부터 끝까지 친절하게 알려주지 않는다.
• 회사마다 필요한 업무 능력이 다르다.
• 질문하지 말고 혼자서 해결하라는 뜻은 아니다. 글로 정리하라는 것이다.
• 효율적인 질문을 하기 전 질문의 범위를 좁히려면 평소 글 쓰는 습관이 필요하다.

글쓰기의 포인트 - 기본 마음가짐

• 개발자는 글 쓰기 전공자가 아니고 프로그래밍 언어를 다루는 사람이다.
• 문학적인 글을 쓸 필요는 전혀 없다.
• 코드의 논리정연함을 그대로 옮기면 좋은 글이다.
• 내가 쓴 글을 볼 사람의 수준을 고려하면 Best of Best.

글쓰기의 포인트 - 코드나 명령어를 먼저 나열한다.

• 개발 관련 글을 쓸 때 보통 핵심은 코드이다.
• 알려주고자 하는 완성된 전체 코드를 먼저 나열한다.
• 코드를 나열할 때는 완성 순서에 맞게 나열한다.
• 중간에 필요한 명령어가 있다면 코드 중간에 넣어준다.
• 다음으로 보여주고자 하는 예제 코드의 핵심 부분을 중심으로 정리한다.
• 핵심 부분 정리가 끝난 상황에서 전체 코드가 길다면 참고 링크로 처리한다.
• 기본적인 API 사용법 등을 설명해야 한다면 해당 부분을 따로 설명하여 전체적인 맥락의 이해를 쉽게한다.

글쓰기의 포인트 - 구조화

• 먼저 전체 주제와 관련된 제목을 정하고 무엇을 설명할 것인지에 관한 요약글을 작성한다. 만약 작성하기가 어렵다면 본문 내용을 먼저 작성한 후 마지막에 정리해 작성한다.
• 코드를 중심으로 주제를 나눈다. 코드에서 설명해야 할 클래스, 메서드, 문법, 예제 코드 설명 등을 중심으로 나누면 된다.
• 해당 부분의 연관성을 전제로 설명하는 글을 쓴다.
• 부가적인 설명을 할 때는 표, 목록, 블록 인용 문자 등을 활용한다.
• 실습형 글 주제는 번호를 붙여서 작성을 하는 것이 좋다.
• 독자 대상에 따라서 최대한 구체화하는 것이 좋다.
• 독자 대상이 초보자라면 트러블슈팅과 관련된 내용을 최대한 챙겨준다.

글쓰기의 본질

• 맞춤법과 오탈자? 치명적인 것이 아니면 지장 없다.
• 알아야 할 부분을 정확하게 기술하는 습관을 가진다.
• 무엇을 말하려고 하는지 대상만 명확하게!

블로그 글 쓰기

블로그 글쓰기 포인트

• 특정 주제를 잡고 연재 형식으로 꾸준히 쓰는 방법
• 내 공부 기록을 꾸준히 남기는 방식
• 누군가에게 보여주는 글인가? 내가 참고하는 글인가? 미리 생각.

블로그 글 쓰기의 포인트 - 누군가에게 보여주는 글

• 가능하면 경어체로 작성하는 것이 좋습니다...
• 부연 설명할 다른 사람의 글 혹은 내 글을 미리 챙겨두면 좋습니다.
• 특정 주제와 관련해 연재 형식으로 꾸준히 쓰는 방법이 좋습니다 (검색 최적화에 유리).
• 카테고리 기반으로 정리하면 좋습니다.