Technical Writing One - 목록 올바르게 사용하기

기술문서에는 가독성을 높이기 위해 목록이 자주 사용됩니다. 이번 포스팅에서는 Google Technical Writing 과정을 참고하여 목록의 유형에 대해서 알아보려고 합니다. 

---

목록의 유형

기술문서 작성 시에 사용되는 목록의 유형은 다음과 같습니다. 

• 글머리 기호 목록
• 번호 매기기 목록
• 포함된 목록(쉼표로 나열한 형태)

글머리 기호 목록은 항목의 순서를 변경해도 목록의 의미가 변경되지 않습니다.

Bash는 다음과 같은 문자열 조작 메커니즘을 제공합니다.
- 문자열 시작 부분에서 부분 문자열을 삭제합니다. 
- 전체 파일을 하나의 문자열 변수로 읽습니다. 

하지만 번호 매기기 목록은 항목의 순서를 변경하면 의미가 변경되므로 목록에 번호를 매겨 작성합니다. 

서버를 재구성하려면 다음 단계를 수행하십시오. 
1. 서버를 중지합니다.
2. 구성 파일을 편집합니다.
3. 서버를 다시 시작합니다. 

포함된 목록은 아래 예시처럼 문장 안에 쉼표로 나열된 형태를 말합니다. 쉼표로 길게 나열된 형태는 기술 정보를 표시하는데 적합하지 않습니다. 포함된 목록을 글머리 기호 목록이나 번호 매기기 목록으로 변환하는 것이 가독성을 높일 수 있습니다.

(Before)
API를 사용하면 호출자가 라마를 생성 및 쿼리 하고, 알파카를 분석하고, 비쿠냐를 삭제하고, 낙타를 추적할 수 있습니다.

(After)
API를 사용하면 호출자가 다음을 수행할 수 있습니다.
- 라마를 생성하고 쿼리 합니다.
- 알파카를 분석합니다.
- 비쿠냐를 삭제합니다.
- 낙타를 추적할 수 있습니다.

 

 

목록에 통일감 주기

영문으로 문서를 작성할 때는 번호 매기기 목록의 항목을 명령문으로 작성하는 것이 좋습니다. 명령형 동사가 문장의 앞에 와서 다음과 같이 작성할 수 있습니다. 실제 영문 매뉴얼의 일부분을 가져와봤습니다.

1. Go to the Screen
2. Click the [ON] Button
3. Click on the recipe editor icon

한글로 작성할 때도 각 항목의 문법이나 어조(?)를 맞춰주면 통일감 있게 문서를 작성할 수 있습니다. 아래 예시에서 수정된 사항은 목록의 어조를 통일시켰습니다. 또한 두 문장으로 작성된 목록을 하나의 문장으로 작성할 수 있는 경우에는 한 문장으로 더 짧게 문장을 수정해봤습니다. 

(Before)
1. Frambus 종료
2. 주요 구성 파일은 /etc/frambus 입니다. ASCII 텍스트 편집기로 이 파일을 엽니다.
3. 이 파일에는 현재 기본값(32)로 설정된 Carambola라는 매개변수가 있습니다. 이 값을 64로 변경합니다.
4. 매개변수 설정을 마치면 구성 파일을 저장하고 종료합니다.
5. Frambus를 다시 시작하세요.

(After)
1. Frambus를 종료합니다.
2. ASCII 텍스트 편집기를 사용해 키 구성 파일 /etc/frambus를 엽니다.
3. Carambola 매개변수를 기본값(32)에서 64로 변경합니다.
4. 구성 파일을 저장하고 닫습니다.
5. Frambus를 다시 시작합니다.

 

 

도입 문구 작성하기

독자에게 목록이나 표가 무엇을 나타내는지 도입 문구를 작성해 설명해주는 것이 좋습니다. 만약 도입 문구가 없이 목록이나 표가 바로 나온다면 무엇을 의미하는지 한눈에 들어오지 않습니다. 

문서에 표, 그림, 목록을 삽입할 때 도입 문구 예시는 아래와 같습니다. 도입 문구 작성이 어렵다면 참고해보는 것도 좋을 것 같습니다. 종종 개발자들이 작성한 문서를 볼 때 작성된 표가 무엇을 의미하는지 알기 힘들 때가 있습니다.😅

(글머리 기호 목록) 다음 목록은 주요 파라미터를 나타냅니다.
(번호 매기기 목록) 프로그램을 설치하려면 다음 단계를 따르십시오.
(표) 다음 표에는 당사 제품의 기능이 요약되어 있습니다.

카카오 디벨로퍼에 있는 또 다른 예시를 가져와봤습니다. 

(글머리 기호 목록) 기능 동작은 다음과 같이 이뤄집니다.
(번호 매기기 목록) 다음은 서비스 회원 가입 처리 과정입니다.
(표) 토큰의 역할과 유효기간을 표로 정리하면 다음과 같습니다.
(표) 차이점은 다음 표를 참고합니다.

---

여기까지 목록을 올바르게 작성하는 방법에 대해서 알아봤습니다. Google technical 강의에 참석했을 때  '왜 독자들은 목록에 끌리는가?'가 토론 주제로 언급되었습니다. 그만큼 목록 형태로 작성되었을 때 가독성이 높아진다는 뜻 아닐까요? 물론 뭐든지 적절하게 사용하는 것도 중요하겠죠?😗

참고자료

https://developers.google.com/tech-writing/one/lists-and-tables