글쓰기 가이드

1부 테크니컬 라이팅 시작하기

1. 테크니컬 라이팅 5단계

1. 계획 세우기
   1. 어떤 독자에게 어떤 주제로 글을 쓸지 정하고 필요한 정보를 수집하는 단계
2. 구조 잡기
   1. 계획 단계에서 수집한 정보를 작업 순서에 따라 차례대로 배열하는 단계
3. 초안 작성
   1. 일단 전달할 정보를 모두 넣음
4. 검토와 재작성
   1. 초안 작성 후 다시 읽어 보며 잘못된 내용과 문장을 확인해 고치는 단계
   2. 검토와 재작성 단계에 가장 많은 시간을 할애한다
5. 배포
   1. 완성된 문서를 독자에게 배포하는 단계

2부 개발자와 테크니컬 라이팅

3. 문서 작성 계획 세우기

1. 대상 독자를 정한다

독자 분석 체크리스트

항목	확인
독자가 원하는 게 무엇인가?
독자는 이 문서를 보고 무엇을 하려 할까?
독자의 기술 수준은 어떻게 되나?
독자가 이미 알고 있는 정보는 무엇인가?
어떤 직업, 어떤 직위에 있는 사람인가?
독자의 학력과 전문 용어 이해 수준은 어느 정도인가?
저자와 독자는 어떤 관계가 있는가?
주제에 관해 독자가 이미 알고 있는 사실은 어떤 것인가?
독자가 이 글을 이해하는 데 필요한 사전 정보는 무엇인가?
독자에게 어떤 반응을 기대하는가?

2. 설명할 기술의 깊이를 조절한다.

ex) 개발자와 비개발자 대상에 따라 깊이가 달라짐.

3. 분위기를 좌우할 어조를 정한다.

4. 주제를 구체적으로 정한다.

주제를 구체적으로 좁혀 나가야 함.

5. 작성할 문서의 종류를 정한다.

• 메일
• 회의록
• 보고서
• 가이드
• 튜토리얼

##

4. 초안 작성

1. 일단 쓴다

2. 명확성, 간결성, 일광성의 3원칙

• 명확성
  • 단호하고 명확한 설명과 표현을 사용해야 함
  • 단정적이지 않은 표현, 추측성 표현 등은 독자에게 신뢰를 주기 어려움
• 간결성
  • 문장을 짧게 유지하고, 단락 역시 5개 안팎의 문장으로 구성
  • 짧고 쉽게 쓰도록 신경 써야 함
• 일관성
  • 문서 전체에서 설명하는 내용이 일관돼야 함.

3. 핵심부터 쓴다

기술 문서는 정확한 내용을 빠르게 전달하는 것이 목적

따라서 핵심을 가장 먼저 써야 함.

역피라미드 방식

결론, 핵심, 주제부터 제시하고 나서 근거나 데이터를 설명하는 방식

중요한 내용을 문서 앞부분에서 설명하고 덜 중요한 내용을 차례로 배치

마지막에는 참고자료나 정보를 추가

4. 제목에 요점을 담는다

제목만 봐도 다루려는 내용이 무엇인지 파악할 수 있게 만들어야함.

압축해서 간결하게 쓰는 것과 필요한 문장 요소를 생략하는 것은 다른 문제. 필요한 문장 요소를 넣어 명쾌한 제목을 만들어야 함

ex) 소셜 네트워크 게임 플렛폼 동향 ⇒ 소셜 네트워크 게임 플랫폼을 활용한 게임 제작 동향

항목	확인
내용이 무엇인지 한눈에 알 수 있는가?
부제목이 필요하지 않은가?
목적와 방법을 명확하게 알 수 있는가?
명사만 나열하지 않고 의미를 정확하게 서술했는가?
널리 알려지지 않거나 표준이 아닌 약어를 사용하지는 않았는가?

5. 문장 하나에는 주제를 하나만 쓴다

문장 하나에 주제가 여러 개 있으면 주제를 파악하는 데 시간이 걸릴 수밖에 없음.

문장 하나에 주제를 하나만 담다 보면 자연스럽게 짧고 쉬운 문장을 만들 수 있음.

6. 객관적인 근거를 댄다

사실을 전달하거나 주장을 펼칠 때 듣는 사람의 동의를 이끌어 내려면 근거를 제시하는 것이 효과적임.

기술 문서에서는 감정에 호소하거나 주관적인 것이 아니라 객관적으로 입증된 명확한 근거를 대야 함.

ex)

예문: A 서버보다 B서버에서 파일을 로딩하는 속도가 훨씬 빨랐다

수정안: 파일을 로딩할 때 A 서버를 이용하면 1.5초, B 서버를 사용하면 0.9초가 걸렸다.

기술 문서에는 추측성 주장이나 입증되지 않은 사실을 적지 않아야 함.

객관적인 수치나 근거를 제시해야 글의 신뢰도가 높아짐.

7. 전문 용어는 독자에 맞게 사용한다

기술 문서는 보편적으로 써야 함. 독자 편에서 생각하고 써야 함. 독자가 원하는 정보가 무엇인지 생각해서 필요한 정보를 독자가 알 수 있는 용어로 전달해야함.

독자가 이해하기 어려운 전문 용어는 피하고 특정 집단만 이해할 수 있는 은어나 줄임말 등도 쓰지 않아야 함.

ex)

예문 : 사용자가 입력한 파라미터 값에 에러가 발생했을 때 나타나는 에러 코드입니다.

수정안 : 사용자 입력 값이 잘못되었을 때 나타나는 오류 코드입니다ㅏ.

8. 용어와 약어를 쓸 때는 풀이를 쓴다

비슷한 분야에서 보편적으로 사용하는 용어가 있다면, 새로 용어를 정의해 만들지 말고 이미 사용 중인 용어를 사용.

ex)

예문 : 스니퍼는 스니핑을 할 수 있는 도구를 말합니다.

수정안 : 스니핑(sniffing)을 할 수 있는 도구를 스니퍼(sniffer)라고 한다. 스니핑은 해킹 기법의 하나로, 네트워크에서 상대방의 패킷 교환을 엿듣는 것을 의미한다. 이렇게 스니핑을 할 수 있는 도구를 스니퍼라 한다.

웹 문서일 때는 별도 용어집 페이지를 만들면 편리함.

약어는 맨 처음 나올 때 풀이한다.

약어 풀이만으로 의미를 모두 전달하기 어려울 때는 설명도 함께 추가

대상 독자 대부분이 쉽게 알 수 있는 약어라면 풀이를 쓰지 않아도 됨.

9. 용어는 일관되게 사용한다.

테크니컬 라이팅은 정보를 빠른 시간 안에 전달하는 것이 목적. 따라서 독자가 혼동하지 않도록 최대한 단순하고 일관되게 작성해야 함.

10. 쉽게 쓴다.

옆 사람에게 말하듯이 쓰자.

5. 시각화 요소로 가독성 높이기

시각 자료는 글로만 표현하기 어려운 생각을 표출하거나 전달할 때 활용하면 좋다.

기술문서에 시각 자료를 주료 사용하는 경우

• 그림이 없으면 설명이 복잡해지고 길어기는 경우
• 복잡한 설정이 필요한 경우
• 화면을 가리키면서 정보를 제공해야 하는 경우
• 그림 외에 표나 목록을 활용하는 것도 굿!

1. 목록을 사용하여 정리한다.

점 목록은 순서와 상관없는 항목을 나열할 때 사용하고, 번호 목록은 단계별로 순서를 나타내거나 그림에 번호를 매기고 번호별로 설명할 때 사용.

점 목록

문장 안의 여러 항목을 순서 상관없이 나열할 때 점 목록을 사용하면 가독성이 높아짐!

점 목록을 쓸 때는 각 항목의 성격이 대등해야 함.

의미상 어떤 항목이 다른 항목에 종속된다면 같은 수준의 점 목록을 사용하지 말아야함.

일반 문장으로 풀어 써야 하는 곳에 점 목을을 습관처럼 사용하지 않아야함.

번호 목록

순서가 중요할 때 사용.

• ex) Firebase API 키 생성 방법은 다음과 같다.
  1. Google Firebase 콘솔에 접속합니다.
  2. CREATE NEW PROJECT를 클릭합니다.
  3. 프로젝트 이름과 정보를 입력합니다.

2. 스크린샷으로 이해도를 높인다.

• 꼭 필요할 때만 넣는다.
• 필요한 부분만 잘라서 넣는다.
• 캡처 환경을 통일한다.
• 그림 크기를 일관되게 지정한다.
• 입력값을 채우고 캡처한다.
• 스크린샷 위에 텍스트를 추가하지 않는다.

3. 정보를 비교할 떄는 표를 활용한다.

표를 사용하여 복잡한 정보를 한눈에 확인할 수 있게 구조화

ex) 시스템 사양

4. 데이터 성격에 맞는 차트를 사용한다.

5. 시각 자료를 쓰기 전에 소개부터 한다.

설명을 생략하고 캡처 이미지만 나열하지 않도록 유의한다.

목록도 마찬가지!

6. 시각 자료를 설명하는 캡션을 활용한다.

캡션(caption)이란 문서의 편집 과정에서 삽입된 그림이나 도표, 사진 등의 이해를 돕기 위해 쓰는 간단한 해설문

그림 캡션 형식 : 그림 + 순차 번호 + 그림 내용 ex) 그림 1 메일 환경 설정

6. 검토와 재작성

1. 객관적으로 문서를 검토

문서를 검토하는 간단한 방법

내가 쓴 글을 다시 볼 때는 객관화하는 것이 중요! 간단하면서 효과적인 방법은 다음과 같다.

• 소리 내어 읽기
• 시간을 두고 다시 읽기
• 온라인 문서라면 인쇄해서 읽기

문서를 검토할 때 챙겨 보면 좋을 체크리스트

항목	확인
내용에 맞는 제목을 달았는가?
목차가 올바른가?
용어를 일관되게 사용했는가?
이해하기 어려운 용어는 없는가?
필요한 정보가 모두 있는가?
불필요한 정보가 있지는 않은가?
내용을 찾기 쉽게 목차를 구성했는가 ?
단락은 적절히 나누었는가?
중복 내용은 없는가?
표현이 명확한가?
객관적인 근거가 있는가?
출처가 명확한가?
외국어나 한자어가 많지 않은가?
피동태가 많지 않은가?
그림이 적절하게 배치됐는가?
표를 적절하게 사용했는가?

2. 맥락에 맞는 적확한 단어를 선택한다.

명확한 문서를 만들려면 맥락에 맞는 적확한 단어와 표현을 사용했는지 확인하고 알맞게 수정해야함.

예문

• KM 클라우드 푸시 서비스를 사용하면 쉽게 푸시 발송을 보낼 수 있습니다. (푸시 발송은 이상한 조합)

수정안

• KM 클라웃드 푸시 서비스를 사용하면 쉽게 푸시 알림을 보낼 수 있습니다.

3. 은어는 형식적인 표현으로 바꾼다.

로그를 까다 ⇒ 로그를 확인하다.

무거운 프로그램 ⇒ 프로그램 실행 속도가 매우 느리다.

로직을 태우다 ⇒ 로직을 적용하다.

에러를 잡다 ⇒ 오류를 수정하다.

뜨면 ⇒ 나타나면

깨지다 ⇒ 제대로 보이지 않는다.

4. 대명사는 일반 명사로 바꾼다.

정확한 사실을 전달하는 것이 목적인 테크니컬 라이팅에서는 대명사를 사용하면 가리키는 것이 무엇인지 명확하게 알기 어려움.

예문

• 업무 캘린더를 사용하면 동료와 쉽게 일정을 공유할 수 있습니다. 또한 이를 통해 프로젝트 진척도도 관리할 수 있습니다.

수정안

• 업무 캘린더를 사용하면 동료와 쉽게 일정을 공유할 수 있습니다. 업무 캘린더에서 프로젝트 진척도도 관리할 수 있습니다.

5. 고유한 이름은 정확히 쓴다

ex)

• Youtube ⇒ YouTube
• MS ⇒ Microsoft
• Win10 ⇒ Windows 10
• AOS ⇒ Android
• IE ⇒ Internet Explorer
• 구글 ⇒ Google

6. 숫자와 단위를 정확하게 쓴다

7. 단정적인 어조로 확신 있게 쓴다

기술 문서는 독자에게 정확한 사실을 전달한다는 믿을을 줘야 함.

~할 것이다, ~하게 됩니다.와 같은 추측성, 완곡한 표현 대신 ~합니다 와 같이 간결하고 명확한 표현을 사용

8. 글꼬리를 뚜렷하게 쓴다

예문)

앞에서 설명한 문제 해결 방법이 유일한 방법이라고 말할 수는 없지 않을까 싶다.

수정안)

앞에서 설명한 문제 해결 방법이 유일한 것은 아니다.

9. 주어와 서술어를 일치시킨다

10. 문장은 짧게 줄인다

문장이 길수록 불필요한 단어나 내용이 추가된 경우가 많으므로, 짧은 문장으로 나누면 좋다.

11. 군더더기 표현을 없앤다

ex) 군더더기 표현 - ‘발생’, ‘필요’, ‘처리’, ‘진행’

예문)

인증서 도메인당 월 8만 원의 비용이 발생합니다.

수정안

인증서 비용은 도메인당 월 8만 원 입니다.

12. 의미가 같은 표현은 한 번만 쓴다

예문)

이전 버전의 오류를 고치고 부족한 점을 보충해, 좀 더 개선하고 보완된 새 버전을 소개한다.

수정안)

버전 1.0의 오류를 고치고 기능을 보완한 버전 2.0을 소개한다.

13. 피동태보다 능동태로 쓴다

피동태로 쓰면 행동의 주체가 모호해지기 때문에 선명한 표현을 써야 하는 기술 문서에서는 꼭 필요할 때만 쓰는 것이 좋다.

예문)

Python은 귀도 반 로섬에 의해 개발되었습니다.

수정안)

Python은 귀도 반 로섬이 개발했습니다.

예문)

결과 로그가 화면에 보여집니다.

수정안)

결과 로그가 화면에 나타난다.

14. 복잡한 번역체를 다듬는다

번역체를 자연스럽게 바꿔 쓰기를 권장.

번역체 - ‘~에 대해’

예문)

자바 스크립트 성능에 대해 알아보자. 성능을 향상시키는 것은 코드 스타일을 다듬는 것에 의해 이뤄질 수 있다. 성능 향상은 다음 3가지 방법을 통해 가능하다.

수정안)

자바 스크립트 성능을 알아보자. 코드 스타일을 다듬어 성능을 향상할 수 있다. 성능 향상은 다음 3가지 방법으로 가능하다. 성능 향상 방법은 3가지이다.

예문) - 자유도가 높다

원하는 기능을 선택해 적용할 수 있어 자유도가 높습니다.

수정안)

원하는 기능을 자유롭게 선택할 수 있습니다.

예문) - ~을 가지고 있다

모바일 기기들은 기종별로 다양한 해상도를 가지고 있습니다.

예문) - ~ 경우

관리 페이지 호출의 경우 다음과 같은 순서로 관리 페이지가 표시됩니다.

수정안)

관리 페이지를 호출하면 다음과 같은 순서로 관리 페이지가 표시됩니다.

15. ‘통해’는 명확한 표현으로 바꾼다

‘통해’ 하나로 여러가지 의미를 대체하면 분명한 문장을 만들기 어렵다.

예문)

네트워크를 통해 전송합니다.

수정안)

네트워크로 전송합니다.

16. ‘무엇은 ~ 무엇이다’ 형식으로 쓰지 않는다

예문)

새로 나온 협업 서비스인 ‘A 메신저’ 서비스를 알아보자. ‘A 메신저’를 사용하면 편리하게 업무를 관리하고 공유할 수 있다.

수정안)

새로 나온 ‘A 메신저’는 편리하게 업무를 관리하고 공유할 수 있는 협업 서비스다.

17. ‘~해 주다’ 대신 ‘~하다’를 쓴다

~주다는 보조동사인데, 보조동사는 본동사와 연결되어 풀이를 보조하는 동사를 말함.

꼭 필요한 곳이 아니라면 덧붙여 쓰지 않아야 문장이 간결해짐.

예문)

Google 계정으로 로그인을 사용하려면 다음과 같이 구현해 주어야 합니다.

수정안)

Google 계정으로 로그인을 사용하려면 다음과 같이 구현해야 합니다.\

18. 조사를 덜어낸다

‘조사’는 명사나 대명사와 같은 ‘체언이나 부사, 어미 따위에 붙어 그 말과 다른 말과의 문법적 관계를 표시하거나 그 말의 뜻을 도와주는 품사’를 말함.

조사를 제대로 사용하지 않으면 다음 예문과 같이 문장이 어색해짐.

‘을/를’을 줄여보자

예문)

시스템 사용을 하기 전에 환경부터 설정을 해야 합니다.

수정안)

시스템을 사용하기 전에 환경부터 설정해야 합니다.

‘의’를 빼보자

예문)

환경 설정의 편리함

수정안)

편리한 환경 설정

19. 재작성한 문서를 동료와 검토한다

자기 검토가 끝났다고 문서를 배포하기에는 이름. 좀 더 객관적인 눈으로 검토할 수 있는 ‘동료 검토’를 거쳐야 함.

검토자는 되도록 대상 독자와 비슷한 지식과 기술 수준을 지닌 사람이 좋다.

외부로 배포하는 문서라면 조직장을 포함해 조직원 전체에게 의견을 받으면 좋다.

잘 쓴 것은 칭찬하기

대안 제시

구체적인 대안을 제시

예문) 개요 절에 개념 설명 보충 바랍니다.

수정안)

개요 절에 푸시 서비스가 무엇인지만 설명했는데, 다른 푸시 서비스와 차별되는 기능을 정리해 추가하면 좋겠습니다. 예를 들어 예약 발송 기능이나 광고 문구 자동 삽입과 같은 기능이요.

빠진 정보 확인하기

동료 검토 체크 리스트

항목	확인
일관된 용어와 표현을 사용했는가?
문서 구조가 논리적인가?
용어나 약어 풀이가 들어갔는가?
앞의 설명과 뒤의 설명에 모순은 없는가?
독자 수준에 맞게 설명했는가?
필요한 설명은 모두 있는가?
그래픽은 필요한 곳에 들어갔는가?
표나 목록을 활용해 더 직관적으로 전달할 부분은 없는가?
문법에 모두 맞는가?
맞춤법, 외래어표기법, 문장부호, 띄어쓰기가 올바른가?

20. 자주 틀리는 맞춤법

문서를 아무리 잘 작성했더라도 맞춤법을 틀리면 문서의 신뢰도가 급격히 떨어짐.

21. 자주 틀리는 외래어 표기법

22. 자주 틀리는 띄어쓰기

23.자주 틀리는 문장 부호

‘.’!?:’ 등이 있음.

마침표(.)

• 문장을 마칠 때
• 날짜를 표현할 때 (2020. 12. 26.)
• 하위 장이나 절을 나타낼 때
• 예) 1장 시작하기 ⇒ 1. 시작하기

쌍점( : )

콜론으로 부르는 문장 부호

• 시와 분, 분과 초 구분 예) 12시 26분 52초 > 12:26:52
• 대(vs) 예) 4대 1로 앞선 상황 > 4:1로 앞선 상황
• 부제목
  • 부제목을 나타낼 때 쌍점은 앞말에 붙여 쓰고 뒷말과는 띄어 쓴다.
  • 예) 개발자를 위한 테크니컬 라이팅 가이드 : 50가지 팁
  • 수정안) 개발자를 위한 테크니컬 라이팅 가이드: 50가지 팁

물결표(~)

기간이나 거리 또는 범위를 나타낼 때 사용. 다른 말이 덧붙을 수 있음을 표시하거나 이를 생략했음을 나타낼 때 사용.

• 범위
  • 2시부터 6시까지 > 2시~6시
• 문장 중 생략 내용 표시
  • 메일에서 ‘회의록은 ~ 참고하세요.’를 확인해 주시기 바랍니다.

큰따옴표(” “)

큰따옴표는 낱말이나 문장을 직접 인용할 때 사용. 책 제목, 신문 이름을 나타낼 때도 사용.

• 직접 인용할 때
  • 배달 앱 기획자는 “앱을 직관적으로 사용할 수 있게 하는 것이 목표였습니다.”라고 말했다.
• 책 제목을 나타낼 때
  • 2021년에 출간된 “테크니컬 라이팅 기본”은 개발자가 글을 쓸 때 참고하면 좋은 책이다.

작은따옴표(’ ‘)

작은따옴표는 문장의 중요한 부분을 강조할 때 사용함. 소제목, 그림이나 노래와 같은 예술 작품의 제목, 상호, 법료, 규정 등을 나타낼 때도 사용함. 인용한 말 안의 인용한 말을 나타낼 때도 씀.

• 인용한 말 안에 있는 인용한 말
  • 예) “시각 자료를 활용하면 이해도가 높아집니다. ‘백문이 불여일견’이라는 말도 있듯이 말입니다”
• 문장 중 중요한 부분을 나타낼 때
  • 문장에서 중요한 부분을 나타낼 때 큰따옴표를 사용하는 일이 많습니다. 데이터를 서로 비교할 때는 ‘표’를 사용하면 좋습니다.
• 소제목을 나타낼 때
  • 문장부호 사용법은 ‘문장부호 바로 쓰기’절을 참고합니다.

소괄호 ()

소괄호는 보충할 내용을 덧붙일 때, 우리말 표기와 원어 표기를 같이 쓸 때 사용.

• 주석이나 보충 내용을 덧붙일 때
  • 이 책은 태크니컬 라이팅(기술 글쓰기)에 관해 다룬다.
• 우리말 표기와 원어 표기를 같이 쓸 때
  • 스미싱(smishing)은 문자 메시지를 사용한 피싱 방법이다.
• 생략할 수 있는 요소임을 나타낼 때
  • 변수 뒤에 조사를 쓸 때는 ‘을(를)’, ‘이(가)’와 같이 씁니다.

해당 가이드는 ‘개발자를 위한 글쓰기 가이드’를 참고하여 만들었습니다.