개발자의 글쓰기(Technical Writing)

원동환·2024년 3월 26일

테크니컬 라이팅(Technical Writing)이란?
테크니컬 라이팅 원칙
테크니컬 라이팅 프로세스
테크니컬 라이팅 팁 요약

개발자들이 대부분 코드 품질은 향상 시키고 구조 개선 등 많은 노력을 하지만 그에 반해 글쓰기는 소홀히 하는 경우가 많습니다. 그리고 대부분의 기술 문서들이 개발 이후에 작성되고 있고 충분한 고민과 시간을 사용하지 못합니다.. 그래서 기술 문서를 읽고도 새로운 커뮤니케이션 비용이 들어가는 경우가 빈번하게 발생하고 있습니다. 그래서 해당 문서에서는 기술 문서를 조금 더 효과적으로 쓰는 방법을 공유하고자 합니다.

테크니컬 라이팅(Technical writing)이란?

테크니컬 라이팅(Technical writing)은 좁은 의미로는 과학 기술 정보를 정확하고 효과적으로 전달하기 위한 문서 작성 기술을 뜻합니다. 넓은 의미로는 모든 유형의 글을 보다 알기 쉽게 전달하는 글쓰기를 통칭하기도 합니다. 문예적인 글(소설, 수필 등)과 같은 글쓰기를 제외한 모든 유형의 글쓰기에서 그 뜻을 분명하고 쉽게 독자들에게 전달하는 것을 목표로 갖고 있습니다. 즉, 개발자 중심의 기술 관련 용어 혹은 설명을 독자가 이해하기 쉽게 콘텐츠를 가공, 관리하며 문서화 작업을 계획하고 수행하는 것을 말합니다.

글쓰기에서 필수로 고려해야 할 사항은 독자를 파악하는 것입니다. 작성한 문서를 가장 많이 읽고 사용할 사람은 누구인지, 그 사람이 해당 문서의 기술, 내용에 대한 기본 지식은 얼마나 있는지 수준을 명확하고 알고 작성을 해야 합니다. 만약 개발자가 본다면 기술적인 용어들을 섞어서 사용해도 상관없겠지만 그게 아니라 개발자가 아닌 사람도 해당 문서를 읽는 경우라면 최대한 쉽게 풀어서 글을 작성해야 합니다.

테크니컬 라이팅은 큰 범주에서 보면 글쓰기의 한 부분에 속합니다. 하지만, 본인의 창작이나 생각을 제외한 사실만을 서술하는 것을 목표로 하며 수식어 및 모호한 표현을 최대한 지양해야 합니다.

테크니컬 라이팅 원칙

테크니컬 라이팅의 목표는 독자가 해당 문서의 기술을 더 빠르게 효과적을 익힐 수 있게 돕는 것입니다. 그래서 아래의 원칙들을 따라 작성하는 것이 필요합니다.

테크니컬 라이팅 4대 원칙

테크니컬 라이팅의 4대 원칙은 명확성, 간결성, 정확성, 일관성입니다.

1. 명확성 (clarity)

명확한 글이란 핵심어나 핵심 문장을 모호하게 사용하지 않고, 대상 독자가 기술문서를 읽을 때 내용의 모호함 혹은 혼란 없이 한번에 이해할 수 있는 글입니다.

명확성이 모호해지는 대부분의 경우는 대상 독자를 제대로 파악하지 못해서 발생합니다. 명확성 예시처럼 본론인 3번을 먼저 설명하고 1번으로 넘어가거나, 사전 작업에 대한 언급을 생략하고 본론을 설명하는 경우가 많습니다. 독자가 구성원 내의 사람인 경우 이런일이 빈번하게 발생합니다. 하지만 사전지식을 알고 있을거라 생각하는건 지극히 주관적인 관점일 수 있기 때문에 사전지식을 충분히 설명한 이후 본론에 대한 내용을 작성해야합니다.

문서를 좀 더 명확하게 적는 방법

핵심부터 씁니다.
- 핵심을 쓴 이후 내용을 뒷받침하는 근거나 설명을 덧붙입니다.
단정적인 어조로 확신있게 씁니다.
- 방법은 세 가지로 볼 수 있다. (X) → 방법은 세 가지다. (O)
번역체는 지양합니다.
- 자바 스크립트 성능에 대해 알아보자. (X) → 자바 스크립트 성능을 알아보자. (O)
은어는 형식적인 표현으로 변경해서 사용합니다.
- 한글이 깨져 보일 수 있습니다. (X) → 한글이 제대로 보이지 않을 수 있습니다. (O)
용어는 정확하게 사용합니다.
- 캘린더를 사용하면 동료와 일정을 공유할 수 있습니다. ~~이를 통해~~ 프로젝트 진척도를 관리할 수 있습니다. → 캘린더에서

2. 간결성 (conciseness)

간결성이란 특정 독자가 기술적인 내용을 신속하고 정확하게 이해할 수 있도록 미사여구나 감탄사 등을 사용하지 않고, 간단하고 쉬운 단어와 간결한 문장을 사용하는 것입니다.

문장을 간결하게 적는 방법

Before

모노레포 형식으로 분리 될 예정으로 각 pt 별로 Sentry 프로젝트를 생성하여 각각pt 별로 이슈 모니터링을 하도록 함

After

모노레포 방식으로 분리할 예정입니다.
각 PT별 센트리(Sentry) 프로젝트 생성 및 이슈 모니터링이 가능하도록 구성했습니다.

무조건 쉽게 사용합니다.
- 전문용어는 최대한 지양한다.
문장은 짧게 사용합니다.
- 기술적인 내용을 신속하고 정확하게 이해할 수 있도록 미사여구, 감탄사 등을 사용하지 않고 간결한 문장을 사용하는 것을 말합니다. 문장을 길고 복잡하게 복문으로 쓰는 것 보단 ‘~은 ~~입니다.' 처럼 단문으로 사용할 때 글이 더 명확 해집니다.
시각화 자료로 가독성 높이기
- 표, 그림, 스크린샷, 차트 등

3. 정확성 (Accuracy)

정확성이란 독자가 필요로 하는 정보를 기술적 오류 없이 정확하게 제공하는 것을 말합니다. 명확성, 간결성보다 훨씬 중요도가 높은 항목으로, 정확성이 없다면 독자가 아무리 시간을 들여서 읽는다 해도 문서를 파악할 수 없게 됩니다.

4. 일관성 (Coherence)

문서의 용어, 표현, 그리고 어조 등을 일관성 있게 사용하는 것을 말합니다. 문서 뿐만이 아니라 일반적인 커뮤니케이션에서도 중요한 원칙입니다.

문서를 일관성 있게 유지하는 방법

예시 – 견적 분석 페이지, 금융사 선택 페이지

두 페이지는 같은 페이지인데 기획에 따라 용어가 섞여서 쓰이기 시작하면서 각각 다른 이름으로 불리는 경우가 있는데 용어는 일관성 있게 유지하기 위해 같은 명칭으로 사용해야 합니다.

용어와 표현은 일관되게 사용합니다.
- 스토리지/저장소 (X) → 이 중 하나로 일관되게 작성
목록과 시각자료를 사용할 때 일관성을 유지
문장부호 작성 규칙은 정확하게 따르기

이외 지키면 좋을 원칙

친근함 (Casual)

어렵고 딱딱한 용어들을 최대한 쉽고 친절하게 고쳐쓰는 것을 말합니다. 전문 용어는 꼭 필요할 때 사용합니다. 문서를 읽는 모든 사용자가 전문 용어에 대해 알지 않습니다. 전문 용어를 사용하는 경우 그 용어를 잘 설명해주고 일관성있게 유지해야합니다.

테크니컬 라이팅 프로세스

Technical Writing의 프로세스로 5단계를 따릅니다.

1. 기획

첫 번째 단계는 문서 기획 단계로, 프로젝트를 시작하는 미팅에서 논의되는 것이 가장 이상적입니다.

문서 작성 범위 – 산출되는 문서의 종류 혹은 콘텐츠가 다양한 경우 이를 고려한 작성 범위를 정의
문서 이해관계자 – 초안 작성자, 테크니컬 라이터, 피어 리뷰 등
프로세스 – 각 프로젝트 특성에 따른 프로세스 정의
문서 작성 도구, 파일 형식 – 문서 작성 도구 선택 (ex. confluence)
문서 일정 - 문서 작성, 검수 및 최종 문서 배포의 일정 수립

2. 구조화

두 번째 단계는 목차 구조화 단계입니다. 기획 단계에서 수집한 정보들을 구조화하여 문서의 목차를 구성하는 단계입니다. 참조 문서들을 잘 분석하고 가독성, 독자의 편의성 등을 고려해야 합니다. 문서의 용도 별 템플릿, 스타일, 목차 구성 가이드를 만드는 게 가장 효과적입니다.

3. 문서 작성

세 번째 단계는 초안을 작성하고 다듬는 단계입니다. 이 단계에서는 전달하고자 하는 내용을 모두 넣는 것에 집중해서 초안을 작성합니다. 국내의 경우 문서화의 중요성에 대한 인지도가 상대적으로 떨어지기 때문에, 문서 작업은 개발과 별개인 부차적 업무로 생각되는 경우가 많습니다. 그래서 개발이 완료된 이후에 문서 작성을 시작하면 대부분 그 이후 새로운 업무에 시간을 뺏기면서 문서 작성에 충분한 시간을 투입하지 못하게 되고 충분히 검토되지 않은 문서가 만들어지기 쉽습니다.

이러한 문제는 문서 작성에 얼마나 많은 시간이 쓰이는지 파악하지 못해서 생기는 이슈인데 ISO/IEC 표준에 따르면 문서 한 페이지의 초안을 작성할 때 1시간이 소요됩니다. 30장의 문서를 작성하기 위해서는 30시간이 필요합니다. 즉, 4일을 온전히 문서 작업에 몰두해야 한다는 계산이 나오는데 이러한 시간들은 현실적으로 어렵습니다.

4. 리뷰

네 번째 단계는 리뷰 단계로 작성된 문서를 기술적인 측면, 스타일적인 측면에서 확인하는 단계입니다. 기술적인 리뷰에서는 문서의 기술적인 내용에 오류가 없는 지에 맞춰서 진행되고, 스타일적인 측면에서는 문서의 구조, 문법, 맞춤법 등에 오류가 없는 지에 맞춰서 진행됩니다.

5. 배포

마지막 단계는 최종 문서를 독자에게 전달하기 위한 배포 단계입니다. 이 단계에서는 기획 단계에서 정한 발행일 및 파일 형식에 맞게 구성해서 배포해야 합니다.

테크니컬 라이팅 팁 요약

사전에 독자의 배경지식과 문화 등을 충분히 이해합니다.
- 독자의 관점을 고려해야 합니다.
- 독자가 얻게 되는 정보를 명확히 합니다.
유사한 콘텐츠를 조사하고 특징을 분석합니다.
독자에 따른 적합한 정보 전달 방식을 채택합니다.
간결한 문장을 사용합니다.
이해하기 어려운 용어는 추가적인 설명을 덧붙입니다.
- 전문용어는 꼭 필요한 경우에 사용해야 합니다. 전문용어를 사용할 경우 추가 설명을 덧붙여야 합니다.
내용의 이해도를 높이는 디자인 요소를 활용합니다.
콘텐츠를 배포하기에 앞서 제 3자에게 검토 받습니다.
- 3자에서 검토받기 전 혼자서 충분히 검토를 한 이후 피드백을 받는 것이 좋습니다.
발행한 콘텐츠를 정기적으로 수정하고 업데이트 합니다.