초간단 문서 작성 가이드

좋은 글은 '독자가 명확하며, 그들의 니즈를 충족시켜 줄 수 있는 글'이에요

그렇다면 어떻게 좋은 글을 쓸 수 있을까요?

이 글을 통해 '좋은 문서를 위한 초간단 문서 작성 가이드'를 소개해볼게요

 

'Docs for Developers 기술 문서 작성 완벽 가이드' 책에서 영감을 받았고,

누구나 쉽게 따라할 수 있도록, 저만의 기준으로 가이드를 재구성했어요

 

다양한 테크닉이 있지만, 핵심은 '독자의 입장에서 내 글을 바라본다'에 있어요

이걸 기억하면 자연스럽게 이해될 테크닉들이 많을 거예요! 

 

---

1️⃣ 독자와 목적 찾기

1. 대상 독자는 누구이며, 그들의 특징은 무엇인가요?
2. 독자가 문서를 읽고 달성하고자 하는 목적(니즈)은 무엇인가요?

 

---

2️⃣ 제목 정하기

1. 제목은 '문서의 목적'을 가장 간결하고 명확하게 표현해야 돼요
   • 문서 하나에 너무 많은 목적을 달성하려 하지 마세요
   • 문서의 목적은 한 가지로만 제한하세요

 

---

3️⃣ 개요 작성하기

1. 먼저, 문서에 필요한 모든 단계를 나열하되 순서는 신경 쓰지 마세요
2. 이렇게 완성된 개요를 아래 항목을 통해 검토하세요
   • 독자가 알아야 할 추가적인 정보가 있나요?
   • 건너뛰거나 완전히 설명되지 않은 단계가 있나요?
   • 단계들을 논리적이며, 이해하기 쉬운 순서로 배치되었나요? ⭐
3. 필요에 따라 단계를 수정하세요 (재배치, 나누기, 합치기..)

 

---

4️⃣ 초안 작성하기

1. 초안은 개요의 순서에 맞게 독자를 안내해야 돼요
2. 초안은 각각의 개요에 자세한 정보를 더하며 주제를 확장해야 돼요

 

📌 소제목

1. 소제목을 통해 단락의 내용을 추측할 수 있어야 돼요
2. 다른 단락과 겹치지 않는 고유한 소제목을 가져야 돼요
   • '테스트'라는 추상적인 소제목보단 'map 함수 성능 테스트'가 더 구체적이에요
3. 소제목들은 일관성 있어야 돼요
   • 문장 형식을 통일하세요 (ex: 제목 정하기, 초안 작성하기)
   • 단어를 혼용하지 마세요 (ex: 메서드, 메소드, method.. X)

 

📌 단락

1. 상단에는 되도록 가장 중요한 정보를 배치하세요
2. 독자의 궁금증을 유발했다면 반드시 답을 제시하세요
3. 가능하면 5 문장을 넘지 않도록 간결하게 만드세요
   • 하위 카테고리를 활용하세요
   • 리스트, 이미지 등의 시각적 요소를 활용하세요
4. 단락들은 일관성 있어야 돼요
   
   • 단어를 혼용하지 마세요 (ex: 메서드, 메소드, method.. X)
   • 단락 구조를 통일하세요 (ex: PREP - Point(주장) - Reason(이유) - Example(근거) - Point(재주장))

 

---

🔎 F 패턴

F 패턴 (출처: 디지털 인사이트, 'F 패턴으로 웹 방문자 전환율 높이기')

 

독자는 우리가 쓴 글을 아주 조금만 읽어요

아주 빨리 읽는 사람도 최대 28%의 단어만 읽는다고 하네요

 

독자는 일반적으로  'F 패턴'으로 글을 훑어봐요

1. 먼저, 문서 상단에서 제목 등의 중요한 정보를 읽어요
2. 아래로 글을 훑다가 관심 있는 문장을 찾으면 그 부분을 읽어요
3. 이후, 아래로 글을 쭉 훑어봐요

그래서 우리는 F 패턴을 따르도록 레이아웃을 구성하는 것이 좋아요

또 제목과 소제목에 글의 핵심을 담는 것이 너무도 중요하구요

 

---

제가 작성한 가이드는 '반드시 따라야 하는 것'은 아니에요

'독자의 니즈'를 생각하며 유연하게 작성하는 것이 더 좋은 글이거든요

다만, 이 글이 문서 작성에 어려움을 겪는 분들에게 도움이 되었으면 좋겠어요 😊