최근에 동료와 기술 문서 작성법에 대해 이야기하다가, "혹시 팁이 있냐"고 물어보더라고요. 저도 기술 문서(예: 설계 문서) 쓰는 걸 좋아하긴 하지만, 전문가라고 할 수는 없어요. 그래도 제가 생각하는 점들을 동료에게 공유했더니 도움이 됐다고 하더라고요. 그래서 이번에는 제가 가장 좋아하는 방식인 글로 정리해봅니다! 😊

여기서 말하는 문서는 기술 설계 문서(TDD), RFC(Request for Comments) 등, 기술적인 아이디어를 피드백과 검토를 위해 전달하는 문서입니다. 꼭 해당 분야에 익숙한 사람이 아니어도 이해할 수 있도록 쓰는 게 중요하죠.

동료와 대화하면서, 저는 세 가지 주요 팁이 있다는 걸 깨달았어요:

1. 헤드라인(요약)부터 시작하기
2. 추상적인 것에서 구체적인 것으로 흐름 만들기
3. 같은 내용을 세 번 설명하기

이제 각 항목에 대해 좀 더 자세히 설명해볼게요.

1. 헤드라인(요약)부터 시작하기

가장 먼저 기억해야 할 점은, 모든 사람이 문서를 처음부터 끝까지 읽지는 않는다는 거예요. 어떤 사람은 앞부분 몇 문단만 읽고 그만둘 수도 있죠. 그래서 가장 중요한 정보를 맨 앞에 두는 게 정말 중요해요.

꼭 "헤드라인"이라는 제목을 붙일 필요는 없지만, 요약(Executive summary)이나 소개(Introduction)에서 핵심 내용을 먼저 전달하면, 독자의 80%에게 80%의 의미를 전달할 수 있어요¹.

예를 들어, 이런 식이죠:

요약

이 제안서는 대규모로 foo 이벤트를 처리할 때 발생하는 문제를 다루고, 이벤트 소싱 아키텍처를 도입해서 이벤트 생산과 소비를 분리할 것을 제안합니다. Kafka가 이 아키텍처에 가장 적합한 기술로 추천되지만, 다른 옵션도 함께 논의됩니다.

핵심:

• 중요한 내용은 맨 앞에!
• 요약/소개에서 80%의 의미를 전달하자

2. 추상적인 것에서 구체적인 것으로 흐름 만들기

문서를 쓸 때마다, 항상 추상적인 것에서 구체적인 것으로 흐름을 만들려고 해요. 즉, 문서 구조상 문제와 그 맥락을 먼저 설명하고, 그 다음에 해결책을 논의하죠.

해결책을 설명할 때도, 전체적인 개요를 먼저 보여주고, 그 다음에 각 구성 요소를 자세히 설명해요.

이렇게 하면 독자가 문서를 읽으면서 점점 더 맥락을 쌓아가며 이해할 수 있어요.
즉, 문제를 먼저 이해하고, 그 다음에 해결책의 큰 그림을 보고, 마지막으로 세부사항을 파악하게 되는 거죠.

예시를 볼까요?

제안

foo 이벤트를 처리하는 고수준 아키텍처는 다음과 같습니다:

1. foo 프로세서가 Kafka에 이벤트를 발행합니다.
2. 한 소비자가 이 이벤트를 읽어 S3에 저장합니다.
3. 또 다른 소비자가 이 이벤트를 읽어 Postgres에 저장합니다.

각 단계는 아래에서 더 자세히 설명합니다.

1. foo 이벤트를 Kafka에 발행하기

…

2. 이벤트를 S3에 저장하기

…

3. 이벤트를 Postgres에 저장하기

…

핵심:

• 문제와 맥락 → 해결책 개요 → 세부 설명
• 독자가 점점 더 깊이 이해할 수 있도록 구조화

3. 같은 내용을 세 번 설명하기

마지막으로, 기술적인 개념을 전달할 때는 세 가지 방식으로 설명하려고 해요.

이게 기술 문서에서 가장 어려운 부분이라고 생각해요.
내가 이해하고 있는 아이디어를, 아직 모르는 사람에게 정확하게 전달하는 게 쉽지 않거든요.
사실, 문서를 쓰는 이유 자체가 바로 이거죠!

오해를 피하려면 다음 두 가지를 조심해야 해요:

• 독자가 "이해했다"고 생각하지만 실제로는 잘못 이해하는 경우
• 내가 설명한 방식 때문에 독자가 이해를 어려워하는 경우

그래서 같은 내용을 세 번 설명하면서:

• 모호함을 줄이고
• 다양한 방식으로 같은 아이디어를 전달하려고 해요.

예를 들어, 다음과 같은 방법을 쓸 수 있어요:

• 문장(서술)으로 설명
• 목록(불릿/번호)으로 정리
• 구성도(아키텍처 다이어그램)
• 시퀀스 다이어그램

아까 예시를 다시 활용해볼게요.

문장으로 설명:

foo 프로듀서는 foo 이벤트를 foo.created라는 Kafka 토픽에 발행합니다. 이 토픽은 두 개의 소비자가 읽게 됩니다: S3 소비자와 Postgres 소비자입니다. S3 소비자는 foo.created 이벤트를 받아 S3에 객체로 저장하고, Postgres 소비자는 새로운 레코드를 Postgres 데이터베이스에 추가합니다.

목록으로 정리:

새로운 foo가 생성되면, 우리는 다음과 같이 처리합니다:

• Kafka 프로듀서에서 새로운 foo.created 이벤트를 Kafka로 보냅니다.
• foo.created 이벤트를 소비해서 S3에 저장합니다.
• foo.created 이벤트를 소비해서 Postgres에 새로운 레코드를 추가합니다.

구성도(아키텍처 다이어그램):

시퀀스 다이어그램:

결국,

"저는 아이디어를 다양한 형식(글, 다이어그램 등)으로 최대한 쉽게 전달하려고 노력합니다."

핵심:

• 같은 내용을 여러 방식(글, 목록, 그림)으로 반복 설명
• 오해를 줄이고, 다양한 독자에게 전달력 높이기

마무리하며

이 팁들이 여러분이 기술 문서를 쓸 때 도움이 되길 바랍니다!
저에게 문서 작성은 계속 배우고, 다듬고, 되돌아보는 여정이에요.
아마 몇 년 후에 이 글을 다시 읽고, 새로운 팁을 추가해야 할지도 모르겠네요.

행복한 문서 작성 되세요! 📚

¹ 이 글의 통계는 전부 지어낸 거예요! 😄

주요 키워드 요약

• 헤드라인/요약
• 추상 → 구체
• 세 번 설명하기
• 오해 방지
• 다양한 형식(글, 목록, 다이어그램)
• 문서 구조화
• 피드백과 검토