1. 계획 세우기 & 구조 잡기
- 무엇을 쓸 것이고, 어떤 내용을 쓸 것인지 구체적이고 명확한 주제 선정.
- 작성자가 가장 자신 있게 쓸 수 있고 확실하게 알고 있으며, 경험담과 사례도 많이 제시할 수 있는 것으로 정하는 것이 좋음
- 어떤 종류의 문서를 작성할 것인지 정한다. (ex. 메일, 회의록, 보고서, 가이드, 튜토리얼
2. 초안 작성
- 생각나는 대로 편하게 글을 쓰며, 쓰고 싶은 내용을 모두 쓴다.
- 독자가 궁금해할 내용, 전달해야 할 내용을 빠짐없이 추가하는 데에만 집중한다.
- 효과적으로 정보를 전달할 수 있게 정리해야 한다.
- 핵심부터 작성한다. / 정확한 내용을 빠르게 전달하는 것이 목적이므로, 핵심을 가장 먼저 작성하고, 내용을 작성한다.
- 제목에 요점을 담는다.
- 문장하나에는 주제를 하나만 쓴다.
- 객관적인 근거를 댄다.
- 전문 용어는 글을 읽는 독자에 따라 선택한다.
ex) 개발자면 전문용어를 알아 들을 수 있지만, 일반 사용자는 알아 들을 수 없다. - 용어와 약어를 쓸 때는 풀이를 쓴다.
ex) 스토리지 <> 저장소, 보안 그룹 <> 시큐리티 그룹, Load Balancer <> 로드 밸런서 - 시각 자료를 적절히 활용한다.
ex) 표, 차트, 설계도, 스크린샷 등 - 목록을 사용해 정리한다.
2-1. 기술 문서를 작성할 때 생각해야 할 3가지 원칙.
- 명확성
다루는 내용이 정확해야 하고 전달하는 방식과 표현도 선명해야 한다. - 간결성
원하는 정보를 빠르게 알리려면 문장을 간결하게 써야한다. - 일관성
앞에서 말한 것과 뒤에서 말한 것이 달라지면 독자는 문서를 믿지 못하므로, 문서 전체에서 설명하는 내용이 일관돼야 합니다.
2-2. 역피라미드 구조 글 쓰기
테크니컬 라이팅에서 널리 사용하는 구조. 일반적인 소설이 피라미드식 구조라면, 역피라미드 구조가 테크니컬 라이팅에서 주로 사용한다.
3. 검토와 재작성 : 초안을 읽어 보며 잘못된 내용과 문장을 확인해 고치는 단계
3-1. 문서를 검토하는 방법
- 소리내어 읽기
- 시간을 두고 다시 읽기
- 온라인 문서라면 인쇄해서 읽기
3-2. 수정해야 하는 요소 : 문장은 짧게 줄인
---
- 맥락에 맞는 적확한 단어를 선택한다.
- 은어는 형식적인 표현으로 바꾼다.
애매모호한 단어보다 형식적인 표현으로 바꾼다.
ex) 무거운 > 실행속도가 느린, 메모리를 잡아먹는, cpu를 많이 사용하는
ex) 로직을 태워 > 로직을 적용해 - 대명사를 사용하지 않고 일반 명사로 바꾼다.
ex) 여기 > API 래퍼런스
ex) 이를 통해 > 업무 캘린더에서 - 고유한 이름은 정확히 쓴다.
- 숫자와 단위를 정확하게 쓴다.
ex) 4G : 4GB || 4GIB // 두 개 다 4G로 표현이 가능함. 1024와 1000은 매우 큰 차이기 때문에, 이를 구분한다. - 단정적인 어조로 확신 있게 쓴다. 글꼬리를 뚜렷하게 슨다.
추측성 어구를 쓰지 말고 확신 있게 사용한다.
ex) 열리게 됩니다. > 열립니다.
ex) 좋을 듯합니다. > 사용합니다. - 주어와 서술어를 일치시킨다.
ex) KM 클라우드가 가지는 장점은 값비싼 서버와 네트워크 등의 장비에 드는 비용을 최소화하고 또한 안전한 보안 서비스도 제공해 줄 수 있다.
>>> KM 클라우드의 장점은 서버와 네트워크 등의 장비 비용을 줄일 수 잇고 높은 보안 서비스를 이용할 수 있다는 것이다. - 군더더기 표현을 없앤다.
ex) 인증서 도메인당 월 8만 원의 비용이 발생합니다. > 인증서 비용은 도메인당 월 8만 원입니다. - 의미가 같은 표현은 한 번만 쓴다.
ex) 과반수 이상 > 과반수 // 과반수에 이상이라는 의미가 내포 됨. - 피동태보다 능동태로 쓴다.
ex) 결과 로그가 화면에 보여집니다. > 결과 로그가 화면에 나타난다. - 복잡한 번역체를 다듬는다.
ex) 자바 스크립트 성능에 대해 알아보자 > 자바 스크립트 성능을 알아보자.
ex) 이번 테스트에서 나타난 문제점 파악을 통해 부족한 기능을 보완하면 판매가 늘 것이다.
>>> 이번 테스트에서 나타난 문제점을 파악해 부족한 기능을 보완하면 판매가 늘 것이다.
ex) 이 책은 기술 문서를 잘 쓰고 싶은 사람에게 도움이 되는 책이다.
>>> 이 책은 기술 문서를 잘 쓰고 싶은 사람에게 도움이 된다.
ex) Google 계정으로 로그인을 사용하려면 다음과 같이 구현해 주어야 합니다.
>>> Google 계정으로 로그인을 사용하려면 다음과 같이 구현해야 합니다.
ex) 자주 사용하는 메뉴는 홈 화면으로 추가해 놓고 사용하시면 편리합니다.
>>> 자주 사용하는 메뉴는 홈 화면에 추가해 사용하면 편리합니다.
ex) 시스템 사용을 하기 전에 환경부터 설정을 해야합니다.
>>> 시스템을 사용하기 전에 환경부터 설정해야 합니다.
ex) 환경 설정의 편리함.
>>> 편리한 환경 설정 - 재작성한 문서를 동료와 검토한다.
1) 동료 검토 준비하기
2) 검토자와 문서 작성자의 태도
잘잘못을 따지려는 것이 아니라, 정확한 정보를 독자 눈높이에 맞춰 이해하기 쉽게 썼는지 확인하고 개선하려는 작업이다. 따라서 의견을 주고 받을 때는 작성자나 검토자 모두 성숙한 태도를 갖춰야 한다.
3) 검토자의 태도
검토자 역시 다른 사람의 문서를 읽으면서 어떤 점을 유의해서 써야하는지 알게 된다.
1. 잘 쓴 것은 칭찬하기
2. '저건 아닌 것 같아요.'와 같은 모호한 의견이 아닌 구체적인 대안을 제시한다.
4) 작성자의 태도
1. 내용 비판을 모욕이나 비난으로 받아들이지 않는다.
2. 받은 의견을 반영하고, 반영하지 않은 것은 검토자에게 이유를 알립니다.
3. 이번에 알게 된 내용은 다음 문서에도 반드시 적용한다.
5) 동료 검토 체크리스트.
수정해야 하는 요소에서 나열한 것들이 잘 작성됐는지 확인한다.
---
5. 배포
- 완성된 문서를 독자에게 배포하는 단계
'개발자를 위한 글쓰기 가이드' 카테고리의 다른 글
| 유형별 테크니컬 라이팅 작성의 원칙 (0) | 2023.02.02 |
|---|---|
| 개발자를 위한 글쓰기 가이드 시작!! (0) | 2023.02.01 |
