2022. 12. 21. 23:57ㆍSoftware Engineering
본 글은 Technical Writing Process의 5단계를 소개하며, 의사소통을 위한 기술적 글쓰기 방식을 소개합니다.
TL;DR
: 체계적인 방법으로 글쓰기를 작성하여 글쓰기의 어려움을 없앨 뿐만 아니라,
글의 내용을 정확하고 효과적으로 전달하기 위해 분명하고 알기 쉽게 작성하는 문서 작성 기술.
: 기획 > 구조화 > 문서작성 > 리뷰 > 배포
Google의 "Software Engineering at Google" 에서는 Documentation의 중요성을 알리며, 실제 구글러들이 사용하는 방식을 안내합니다. 해당 내용은 Documentation - Software Engineering at Google 에 정리되었습니다.
What is Technical Writing?
: 글의 내용을 정확하고 효과적으로 전달하기 위해서 분명하고 알기 쉽게 작성하는 문서 작성 기술
글에 대한 두려움을 갖는 사람들이 많고, 어쩌면 이 글을 읽고 있는 당신일 수도 있습니다.
구두로는 잘 설명할 수 있는데 글로 쓰자면 숨부터 막히곤 하죠.
개발자들은 글을 못쓴다.
한 번쯤은 들어봤을 법한 말입니다. 부정하기에도, 그렇게 틀린 말도 아닌 것 같습니다.
정말 개발자들은 글을 못쓸까요?
글을 못쓴다고 생각하는 이유를 적어보도록 합시다.
✔ 일단 시작부터 어떻게 할지 모르겠다
✔ 내가 무엇을 했는지를 정리하기기 귀찮다
✔ 대충 알아볼 수 있지 않나?
✔ 내가 왜 이 고생을 해야 하지?
✔ 이 정도만 보여주면 어떻게 잘 찾아보겠지
✔ 무엇에 대해 글을 써야 할지 막막하다
✔ 잘 쓰고는 싶은데 어떻게 하는지 모르겠다
✔ 생각을 표현하기 어렵다
✔ 한 편의 글을 쓰는 데 너무 많은 시간이 걸린다
✔ 시간이 없고 바쁘다
...
어떤가요? 대부분의 개발자가 공감하는 부분이 적지 않을 것 같은데요. 개발자가 아닌 사람들도 어렵고, 귀찮고, 바쁘다는 이유로 글쓰기를 어려워 하곤 합니다.
"개발자는 글을 못쓴다"는 말, 그냥 들으면 억울하니 이유라도 알아내서 해명을 해봅시다.
공학 수업의 문제점
기술적인 글쓰기를 아울러 기존의 공학 글쓰기 교육의 문제점을 잘 다룬 "공학글쓰기 이해", 권성규 논문에 따르면, 공학교육인증의 도입으로 인해 공과대학에 글쓰기 과목들이 개설되었지만 아직까지 아래와 같은 문제로 인해 안정화되지 않는다고 주장합니다.
✔️ 글쓰기 과목은 전임 교원이 없다.
: 주로 국문학, 언어학, 작문학, 인문학 학자들이 가르치고 있으며, 본인의 전공보다 글쓰기 교육에 몰입하는 드물다.
✔️ 글쓰기 교육의 방향 설정이 산별적이다.
: 다양한 학자들의 합의하에 그들의 경험을 바탕으로 전공의 틀에 맞게 진행된다. 즉, 교수들의 역량에 따라 교육 방향이 산별적으로 진행된다.
공학 글쓰기는 기존의 인문학적 관점과 소양의 글쓰기보다 의사소통을 목적으로 하는 표현을 중심으로 다뤄져야 합니다. 또, 공학적인 글쓰기를 전문적으로 교육할 수 있는 체계적인 시스템이 필요합니다.
공학적인 글쓰기 교육에 대한 내용을 간단히 살펴보았는데요. 전문적이고 체계적인 교육을 요구하는 공학적인 글쓰기는 왜 중요한 것일까요?
의사소통으로서의 기술 글쓰기
하루에 수 십번 다양한 형태를 통해 본인의 의사를 전달하고 상대방의 의사를 듣는 의사소통을 합니다. 팀원들과 의사소통 하는 것이 주된 일과 중 하나이기 때문에 원활한 의사소통 능력은 꼭 필요한 역량이기도 합니다.
의사소통 능력
: 전문화된 기술 내용을 문서 및 구두로 자신의 의사를 원활히 전달할 수 있는 능력과 상대방의 의사를 비판적으로 들을 수 있는 능력.
비즈니스 의사소통은 주로 문서로 이뤄지기 때문에 문서를 더욱 잘 작성할 필요가 있습니다. 전문화된 문서는 읽는 사람의 이해를 도울 뿐만 아니라 많은 시간을 단축해줍니다.
보고서, 제안서, 메모, 이메일, 회의록, 회의, 발표, 표, 그래프, 수식, 통계 분석 ...
다양한 형식의 문서를 작성하고 메신저들을 전달하는 것은 셀 수 없이 일어나며, 평생해야 할 일 중 하나입니다. 평생 뗄 수 없는 글쓰기 능력을 갖추기 위한 기술이 바로 Technical Writing이며, 전문적이고 체계적인 프로세스를 갖춘 글쓰기를 위한 기술입니다.
Technical Writing Process
Technical Writing이란, 글의 내용을 정확하고 효과적으로 전달하기 위해서 분명하고 알기 쉽게 작성하는 문서 작성 기술입니다. 전달할 주제를 먼저 언급하는 두괄식, 간결한 문단, 독자가 쉽게 이해하도록 일반적이고 분명한 문장과 단어 선택을 강조합니다. 즉, 필자가 핵심내용을 정확(correct), 간결(concise), 명확(clear)하게 씀으로써 독자가 쉽게 이해하도록 하는 글쓰기 방식입니다.
해당 글에서는 Technical Writing을 위한 글쓰기 프로세스를 소개합니다. 기술적인 글쓰기는 다양한 방식으로 소개되고 있는데, 대부분의 방향성과 이론은 동일합니다. Kieran Morgan의 Technical Writing Process라는 책에서 소개하는 기술적인 글쓰기 과정인 Plan > Structure > Write > Review > Publish 을 인용하여, 책에서 제시하는 단계에 개인적으로 학습한 내용을 담아 소개하고자 합니다.
소프트웨어 개발 프로세스 중 폭포수 모델과 비교하면 학습에 도움이 될 텐데요. 아래의 그림을 참고하여, 기술적인 글쓰기 단계를 소프트웨어 개발 프로세스의 각 단계와 비교해서 이해할 수 있습니다.
그럼 지금부터 기술적인 글쓰기를 각 단계 별로 알아보겠습니다.
1/ Plan
: 기술 문서 작성 전, 주제/대상 독자/ 도구선정/ 일정 수립 등을 정하는 준비 단계
“If you fail to plan, you plan to fail.”
어떤 주제를 다룰지, 그리고 어떤 독자를 대상으로 문서를 작성할지 계획하는 단계입니다. 소프트웨어 개발 프로세스에서 기획 및 요구 사항 분석과 비슷한 개념입니다.
✔️ 주제
머릿 속에 있는 주제를 먼저 명확히 정의해야 글의 내용을 더 명확하게 잡고 갈 수 있습니다. 단어 몇 개로만 주제를 지정하면 모호한 상태로 시작될 가능성이 있는데, 마치 허술한 스펙 규격으로 개발을 시작하는 것과 동일합니다. 가능한 문장 형식으로 주제를 주어/목적어/서술어로 작성하여 어떤 일을 하는지 왜 하는지 어떻게 할 것인지를 생각해보아야 합니다.
정리하면 아래와 같습니다.
- 정확한 주제 선정
: 글의 방향성을 명확히 지정하여 글의 문맥이 엉뚱한 방향으로 흘러가지는 않는지, 쓰려는 글이 주제와 상관없지는 않은 지 등을 판단합니다.
✔ 주어/목적어/서술어로 작성
: 어떤 일을 하는지 왜 하는지 어떻게 할 것인지를 주어/목적어/서술어로 표현해서 명확한 주제를 생각합니다. 만약 주제를 단어 몇 개로만 지정한다면 모호한 상태로 시작될 수 있으니 완전한 문장으로 적는 것을 권장합니다.
주제를 먼저 정확하게 정의해 놓으면 한 문장이든 한 단락이든 글의 타당성을 가늠해볼 수 있습니다. 가령 글의 방향이 엉뚱한 방향으로 흘러가지는 않는지, 혹은 작성하려는 글이 주제와 상관없지는 않은지 등을 판단할 수있습니다.
| 변경 전 | 변경 후 |
| 문서의 제목 - A 사가 제공하는 OPEN API Guidelines |
문서의 제목 - A 사가 제공하는 OPEN API Guidelines |
| 문서의 주제 - A 사가 제공하는 OPEN API 사용법 |
문서의 주제 - A 사가 제공하는 OPEN API을 사용하기 위해서 RESTful API의 개념과 A 사에서 사전에 정의한 네트워크 통신 규약을 소개한다. |
✔️ 대상 독자
"누가 이 글을 읽을 것인가, 필자와 어떤 관계인가, 주제와 관련해 어떤 정보를 가지고 있는가" 를 고려해봅니다. 글을 작성하기 전 대상 독자를 먼저 파악하여 문서의 수준과 방향을 결정합니다. 대상 독자를 미리 설정하는 것은 기술적 글쓰기에서 굉장히 중요하게 다루는 요소입니다. 독자와 글쓴이의 관계 및 독자가 가지고 있는 정보에 따라 글의 수준과 방향이 결정됩니다.
글쓰기 전에 대상 독자를 선정하는 이유는 다음과 같습니다.
- 상대방이 알고 싶어하는 정보를 전달
- 독자의 기술적 깊이를 고려하여 문서 작성
대상 독자의 기술적 깊이를 고려해야 하는 이유를 아래 예시를 통해 알아보도록 하겠습니다.
Example.
서비스 개발을 할 때 오류 메세지를 작성할 때를 떠올려 보세요. 오류를 읽는 사람이 누구인지에 따라 그 문구가 달라집니다. 만약 사용자가 API를 직접 사용하는 개발자라면 오류 메세지를 아래와 같이 적을 수 있습니다.
개발자를 대상으로 전달하는 오류 메세지:
1. MySQLIntegrityConstraintViolationException: Duplicate entry ‘gngsn’ for key ‘PRIMARY’.
2. [StatusCode 400] NullPointException: Profile Detail 조회 API에 userId 검증 오류.
3. JWT 검증 Signature가 다름. ex: 다른 환경에서 발급한 토큰을 사용 - token : eyJhbGcJ9.eyJzdmNDZCI6.3giAo
문장의 내용이 간결하기 때문에 빠르게 파악하고 디버깅하기에 용이합니다. 하지만 이 장점은 백앤드 애플리케이션 개발자들로 한정된 내용입니다. 위의 오류 메세지를 해당 분야와 상관없는 독자가 봐야 한다면 아래와 같이 적어야 합니다.
비개발직군을 대상으로 전달하는 오류 메세지:
1. MySQL 데이터베이스에 데이터 입력 중 PRIMARY 제약조건에 위반하는 중복된 데이터 ‘gngsn’가 발견되어 오류가 발생했습니다.
2. 상세 Profile 조회 시, 유저의 ID 값은 필수 값입니다.
3. 유저 인증 과정 중 유효하지 않은 서명 값 발견 (가령, 다른 개발 환경(alpha, qa 등)에서 발급한 토큰 사용할 때 발생할 수 있습니다)
- 유저의 인증 요청 값: eyJhbGcJ9.eyJzdmNDZCI6.3giAo
대상 독자를 미리 정의해두면 문서의 수준이나 기술적 깊이를 일관되게 유지할 수 있습니다. 위의 예시와 같이 두 가지 형식의 오류 메세지는 동일한 내용을 의미하지만, 대상 독자에 따라 서로 다른 문장을 만들어 지는 것을 확인할 수 있습니다. 대상 독자가 가진 지식의 깊이와 이해도를 고려하여 문장을 다르게 작성해야 함을 이해하셨나요? 글의 방향과 문서의 깊이를 결정하는 중요한 요소 임을 다시 한 번 강조하고 넘어가겠습니다.
✔️ 도구 선정
문서 작성 도구 사전 협의 파일 형식 문서 파일 형식 정의합니다. 가령 Google Docs, Wiki, Notion, Markdown Editor 등을 사용할 수 있습니다. 작성 뿐만 아니라 문서를 최종적으로 추출할 때에도 Export 파일 형식이 다를 수 있으므로, 파일 산출 형식(PDF, HTML 5 등)을 정의합니다. 만약, Web으로 제공 시에는 보안 사항 등도 함께 정의해야합니다.
✔️ 일정 수립
문서의 작성 과정에 따른 일정 수립을 지정합니다. 관련 템플릿 전달, 초안 완료, 1차 검수본 전달, 2차 검수본 전달, 피어 리뷰 완료, 최종 문서 배포 등의 일정을 수립합니다. 문서 작성 시 일정을 수립하는 이유는 개발 시에 일정 수립 과정이 필요한 이유와 동일합니다.
2/ Structure
: 관련된 정보끼리 묶고 논리적 순서대로 문서 구조를 잡는 단계
기술적 글쓰기의 두 번째 Structure 단계는 문서의 기본적인 구조를 잡는 단계입니다. 개발에서 아키텍처를 설계하는 것과 비슷할 수 있습니다. 해당 단계에서는 크게 소재 정리와 목차 구성을 수행 합니다.
✔️ 소재 정리
: 관련된 정보끼리 묶기
사전에 준비한 소재를 관련이 있는 것끼리 묶어 논리적인 순서로 나열합니다. 글을 쓰기 위해 사전에 수집해둔 정보들이 있을 텐데요. 그 소재들을 관련이 있는 것끼리 묶어서 각 묶음의 관계를 생각해보는 단계입니다.
대표적인 소재정리 방법에는 마인드맵이 있습니다. 마인드맵은 생각 체계화, 기억력, 이해력을 증진시키는 도구로 알려져 있습니다. 먼저 소재들을 밀접한 관련이 있는 단어 혹은 문구로 표현한 후 관련있는 개념들을 묶어서 그룹을 만든 후 상호간의 관계를 정의해봅니다.
마인드맵은 오프라인에서 뿐만아니라 온라인 상의 웹 사이트나 프로그램을 쉽게 찾아볼 수 있습니다. 필요하다면 2022년을 기준으로 마인드맵 사이트의 순위를 매겨놓은 사이트를 참고하시길 바랍니다.
✔️ 목차 작성
소재를 정리한 뒤 정보 묶음을 논리적인 순서로 나열합니다. 독자가 어떤 순서로 읽어야 더 잘 이해할지를 생각해보는 것입니다. 서로 관련있는 개념과 내용을 묶어둔 소재를 정리한 후에는 트리 구조로 변경하여, 상하위 범주를 구성합니다. 어떤 소재를 상위 범주로 삼을지, 어떤 하위 범주들을 가지는 지를 따져보아야 합니다. 빠진 내용, 중복된 내용, 관련이 없는 내용이 동일한 상위 범주 아래에 있는 것은 아닌지 확인해봅니다.
이 때, 상하위 개념의 수직적 깊이와 같은 레벨 상의 수평적 너비의 균형을 맞추는 것을 권장합니다. 상위 제목은 3 단계까지 있는데 독단적으로 상위 범주 내의 하위 범주들이 밀접하게 구성되어 있다면 여러개의 상위 범주로 넣어야 할 것을 하나의 상위 범주로 넣은 것은 아닌지 확인해 보아야 합니다. 이는 문서의 흐름을 전반적으로 주제에 따라 균형있게 작성할 수 있습니다.
좋은 예시로 Reactor Project 공식 페이지를 참고할 수 있습니다. 각 제목 수준에 맞는 Heading 레벨으로 번호를 매기고, 관련된 내용을 묶어 하나의 카테고리로 지정한 것을 확인할 수 있습니다. 또, 상/하위 범주와 대등한 레벨에서 제목이 겹치지 않은지 살펴보아야 합니다.
목차의 순서는 숲에서 나무를 볼 수 있도록 구성합니다. 아래를 참고하여 글쓰기 시 사용자가 이해하기 편한 순서로 구성했는지를 확인해보아야 합니다.
✔️ 기본 정보 👉🏻 부가 정보
✔️ 쉬운 정보 👉🏻 어려운 정보
✔️ 원인 👉🏻 결과
✔️ 이론 👉🏻 예제
✔️ 작업 진행 순서
✔️ MECE 검증
: 내용 작성: 작업 순서에 따라 구성, 시각 자료 활용
목차를 구성한 다음에는 잘 구조화된 목차인지 확신이 들지 않을 수 있습니다. 목차를 잘 구성해야 다음 단계로 넘어갈 수 있기 때문에 한 번 더 확인하고 가는 것이 좋습니다.
그 방법으로 MECE 검증을 활용할 수 있습니다. MECE는 "Mutually Exclusive Collectively Exaustive"의 약자로, "서로 중복되지 않으며, 전체적으로 누락이 없도록 한다"를 의미합니다. 상호 배제됨 없이 누락되지 않게 수집하는 것을 의미하며 쉽게 말해서 중복되는 것은 없는가, 누락된 것은 없는가를 질문해보는 방법입니다.
예를 들어 "ABC 제품"에 필요한 "기능"을 MECE 검증해본다고 했을 때, 제품에 필요한 성질(예. 건강 기능)과, 없어야 할 성질(예. 유해 성분)을 빠짐없이 검토해 보는 것입니다.
“서로 중복되지 않으며, 전체적으로 누락이 없록 한다”
3/ Write
위에서 나열한 목차를 기반으로 각 소주제 별 본문을 채워 넣습니다.
이 때 제목 아래에 바로 소제목이 오지 않도록 주의해야 합니다. 카테고리마다 적절한 설명을 담은 본문을 적습니다. 만약 적을 말이 없다면 목차가 제대로 구성된 것인지를 의심해볼 필요가 있습니다. 상/하위 관계가 맞는지, 혹은 불필요하게 추가된 카테고리는 아닌지 확인해보아야 합니다.
✔️ 문장
본문은 여러 단락으로 구성되며, 단락은 여러 문장으로 구성됩니다. 단락을 작성하는 방법은 중심 문장을 적고 뒷받침 문장을 더해 하나의 단락으로 만듭니다. 하나의 단락에 중심 문장이 여러개 오지 않도록 주의하세요.
예시를 하나 확인해보겠습니다. 아래 문단을 살펴보면 중심 문장을 가장 먼저 제시하고 뒷받침 문장들이 따라오는 것을 확인할 수 있습니다.
단락은 글쓰기에서 하나의 중심 생각을 이루는 단위다. 단락은 하나 이상의 문장으로 구성된다. 문장은 명확하며 확실한 구조를 갖추고 있다. 이에 비해 단락은 덜 명확하다. 단락 구조는 유연하며, 글쓴이는 문장을 연결해 효과적으로 단락을 구성하는 법을 배워야 한다.
단락에는 세 가지 기능이 있다. 1) 글 전체의 주제를 논리적으로 나눈다. 2) 글을 물리적으로 식별 가능한 단위로 나눠 가독성을 높인다. 주제문에 표현된 중심 생각을 논리적으로 완성한다.
단락 길이는 너무 길거나 짧지 않아야 한다. 너무 짧으면 흐름이 끊어지고, 너무 길면 읽기 힘들다. 잘 쓴 단락은 독자가 읽기 편한 길이 내에서 중심 생각을 전달한다. 단락을 재구성해서 너무 짧은 단락은 합치고 너무 긴 단락은 나눈다.
- Writing Effective Paragraph
문장은 문서의 대부분을 이루는 단위입니다. 따라서 각각의 문장을 읽기 좋게 작성해야 문서도 읽기 좋은 방향으로 구성됩니다. 테크니컬 라이팅에서는 문장 작성 시 반드시 지켜야 할 몇 가지 규칙들이 있습니다. 이 규칙들은 글쓰기에 좋은 가이드라인이 되어 줍니다. 지금부터 이 규칙들을 살펴보도록 하겠습니다.
✔️ Technical Writing 4대 원칙
테크니컬 라이팅에서는 글을 작성할 때 명확성, 간결성, 정확성, 일관성을 지켜야 합니다. 글을 작성할 때 반드시 고려해야 하는 핵심 사항입니다. 해당 내용은 테크니컬 라이팅 4대 원칙의 제목으로 🔗 카카오 기술 블로그에서도 다루고 있습니다. 카카오 기술 블로그에서는 조셉 퓰리처의 명언을 인용하며 글을 시작합니다.
테크니컬 라이팅의 4대 원칙인 '명확성', '간결성', '정확성', '일관성'을 나타내는 문장입니다. 4대원칙의 의미는 아래와 같습니다.
📌 명확성 Clarity
핵심이나 핵심 문장을 모호함이나 혼란없이 정확하게 표현
명확성은 모호하게 사용되지 않고, 대상 독자가 기술 문서를 읽을 때 혼란없이 한 번에 이해하는 글입니다. 특정 부분을 몇 번이고 다시 읽게 된다면 명확성이 떨어지는 글입니다.
- 이중부정 지양
❌ 사용 금지 X
✅ 사용 금지
- 사람이 주어일 때 수동 표현 지양
❌ 편집 버튼이 클릭되어야 해당 항목을 편집할 수 있습니다.
✅ 사용자가 편집 버튼을 클릭하여 해당 항목을 편집할 수 있습니다.
- 문맥에 맞는 조사 사용
❌ 새로운 기사가 발행합니다.
✅ 새로운 기사를 발행합니다.
- 중복 높임 지양
❌ 아래의 3가지 항목에 대한 설명을 확인하시고 설정하세요.
✅ 아래의 3가지 항목에 대한 설명을 확인 후 설정하세요.
📌 간결성 Conciseness
: 꼭 필요한 문장으로 빠르고 정확하게 이해할 수 있게 표현
간결성이란 특정 독자가 기술적인 내용을 신속하고 정확하게 이해할 수 있도록 간단하고 쉬운 단어와 간결한 문장을 사용하는 것을 의미합니다. 특히 테크니컬 라이팅은 기술적인 문서를 작성하는데 자주 사용되기 때문에 신속하고 정확하게 이해되어야 합니다. 간결한 문장을 위해서는 중복된 단어를 없애고 불필요한 꾸밈 말인 미여사구는 없는 지 확인합니다.
- 불필요한 부사 제거
❌ 인증 메일을 성공적으로 전송했습니다.
✅ 인증메일을 전송했습니다.
- 불필요한 수식어 제거
❌ 선택하신 파일을 삭제합니다. 정말 삭제하시겠습니까?
✅ 선택한 파일을 삭제하시겠습니까?
- 긍정문을 사용하여 간결한 문장 지향
❌ 등록된 시간 만큼은 근무 시간에 포함되지 않습니다.
✅ 등록된 시간은 근무 시간에서 제외됩니다.
- 한자 사용 시, 중복 표현 사용 지양
❌ 세션 정보는 지속적으로 유지됩니다.
✅ 세션 정보는 유지됩니다.
📌 정확성 Accuracy
정확성이란 독자가 필요로 하는 정보를 기술적 오류 없이 정확하게 표현
- 정확한 단위 사용
❌ 가로 크기 800
✅ 가로 크기 800px
- 최소/최대 값 등 정확한 내용 기입
❌ 댓글은 최소 10자까지 입력해야 합니다.
✅ 댓글은 최소 10자이상 1000자 이하로 입력해야 합니다.
- 지시 대명사 사용 지양
❌ 사전 설정은 이곳을 참고해 주세요.
✅ 사전 설정은 사전 설정 챕터를 참고해 주세요.
📌 일관성 Coherence
: 문서에 용어, 표현, 그리고 어조 등을 일관되게 표현
독자 입장에서 조금이라도 오해할 만한 여지를 남기면 안 되기 때문에 문서의 일관성 유지가 필수
일관성 없는 문서는 신뢰도와 가독성이 저하됩니다.
- 일관된 명칭 사용
❌ 토비, 토비의 스프링, 토비의 스프링 3.1, Toby Spring
✅ 토비의 스프링 3.1
- 일관된 표현 사용
❌ 개인 정보 수집 동의 버튼을 체크해주세요. 쿠키 사용 여부를 선택해주세요.
✅ 개인 정보 수집 동의 버튼을 선택해주세요. 쿠키 사용 여부를 선택해주세요.
- 일관된 표현 사용
❌ 자동 방지 문자를 정확하게 타이핑합니다/칩니다.
✅ 자동 방지 문자를 정확하게 입력합니다.
✔️ 목록
단락을 구성하는 방식으로 목록을 사용할 수도 있습니다. 목록은 유저가 동등한 구성을 보기에 아주 적합한 형식인데요. 순서없는 동등한 항목이라면 점 목록을 사용하고 순서가 있는 항목이라면 번호 목록을 작성합니다. 목록을 사용한다면 반드시 어떤 내용을 나열했는지 설명을 추가해야 합니다.
✔️ 시각 자료
독자가 내용을 이해하기 쉽게 시각 자료를 사용할 수 있으며, 시각 자료도 단락으로 봅니다. Sung and Mayer (2012)의 연구에 의하면 독자들은 문서에 그래픽을 제공할 때 더 높은 만족도를 보인다고 합니다. 또, 백문이 불여일견이라는 말이 의미하듯이 시각 자료는 이해를 더해주는데 큰 도움이 됩니다.
시각 자료는 글쓰기 준비 단계부터 고려하는 것이 좋습니다. 시각 자료는 제공하는 정보에 따라 적절한 형태로 제공해야 합니다.
- 그림, 사진 : 사물을 묘사하거나 생김새를 표현
- 표, 그래프 : 수치나 양질 표현
- 구조도 : 구조 또는 관계 등 논리적인 흐름을 표현
시각 자료를 활용하는 것은 추천하지만, 다음과 같은 사항에 주의해야 합니다.
- 시각 자료는 설명하는 대목 가까이에 배치
- 그림에서 사용하는 용어는, 특히 표나 그래프에서, 일관성 있게 사용
(잘못된 예. 문장에서는 비율로 표현하고 그림에서는 백비율을 표시)
- 저작권 주의
- 신뢰할 수 있는 문서를 위해 권위 있는 출처의 최신 데이터를 사용
- 그림에서 개인 식별 정보와 보안 사항은 반드시 가려야 함
- 글을 잘 보조하는 적절한 그림을 사용
예. 문장을 보조하는 적절한 그림
“Linked List 자료구조는 각 노드마다 내용과 다음 리스트에 대한 참조(Pointer)를 가지고 있습니다.”
아래 세 개의 그림 중 위의 문장을 보조하는데 가장 적합한 그림은 어떤 것일까요?
세 개의 그림 중 위의 문구를 보조하는 그림을 찾는다면 아래와 같은 이유로 '그림 3'입니다.
그림 1. BAD.
- 체인은 예쁘지만 정보가 없음
- 서로 연결된 목록이 앞과 뒤를 모두 가리킬 수 있음을 잘못 암시
그림 2. OKAY.
- 첫 번째 항목이 두 번째 항목을 가리키고, 두 번째 항목이 세 번째 항목을 가리킨다는 것을 알 수 있음
- 제시된 문장에서는 내용과 포인터를 모두 참조하지만, 그림에서는 '포인터'는 표시되어 있지만 '내용'은 표시되지 않음
그림 3. GOOD.
- 가장 적합하고 유익한 정보를 제공하는 그림
- 그림이 포인터 부분으로부터 각 노드의 내용 부분을 명확하게 묘사
✔️ 코드
🔗 구글의 Technical Writing Course 페이지에서는 좋은 샘플 코드는 종종 최고의 문서가 된다는 내용과 함께 아래의 문구를 같이 담았는데요. 코드 샘플을 넣을 때에는 내용과 일치하고, 정확하고, 빠르게 이해할 수 있고, 재사용이 용이한 코드를 사용하라고 제시합니다.
“Good samples are correct and concise code that your readers
can quickly understand and easily reuse with minimal side effects.”
위 문구의 키워드를 정리하자면 아래와 같습니다.
- Correct: 내용과 일치하는 코드
- Concise: 정확한 코드
- Quickly understand: 이해하기 쉬운 코드
- Easily Reuse: 사이드 이펙트를 최소화하는 재사용성
코드 자료의 예시를 살펴보겠습니다.
코드 자료를 활용할 때에는 다음의 몇 가지 사항을 고려해볼 수 있습니다:
(1) 반드시 코드에 대한 설명 작성
(2) 제품을 사용하는 가장 좋은 방법으로 제시
샘플 코드는 사용자가 코드를 작성하는 방식에 직접적인 영향을 미치기 때문입니다.
(3) 항상 샘플 코드를 테스트
시간이 지남에 따라 시스템이 변경되고 샘플 코드가 손상될 수 있기 때문입니다.
4/ Review
: 문서 구조 확인, 문법/맞춤법 수정 (검토 단계)
개발을 마치고 코드 리뷰나 QA를 통해 개발이 잘 되었는지, 잘 작동하는지 테스트를 합니다. 테크니컬 라이팅에서도 동일한 과정이 필요합니다. 글을 수정하고 다시 작성하는 단계가 필요합니다. 개발 프로세스에서 QA 단계의 중요성은 다들 아실 텐데요. 수정 추가 단계가 계속 이뤄지는데 문서 작성 과정도 동일합니다.
✔️ 문서 수정
테크니컬 라이팅에서 리뷰 단계는 원래 주제에 맞게 잘 적었는지, 문서의 수준은 설정한 독자에 수준에 맞게 되어 있는지, 문서의 목차 구조는 독자가 읽고 이해하기 쉽게 되어 있는지를 확인, 문법 오류 맞춤법 오류 등을 확인합니다. 주제와 대상 독자를 다시 설정하거나 문서를 원래 목적에 맞게 수정합니다. 목차 역시 검토 결과에 따라 수정할 수 있습니다.
작성된 문서를 기술적인 측면과 스타일 적인 측면에서 확인하는 단계입니다. 기술적인 리뷰에서는 문서의 기술적인 내용에 오류가 없는지에 초점을 맞춰 진행되며, 보통 초안 작성자와 초안 작성자가 속한 팀 내의 다른 개발자가 진행합니다.
기술적 리뷰는 오류를 수정할 수 있는 단계로 되돌아가 문서 작업을 진행합니다.
스타일적인 리뷰는 동료 테크니컬 라이터와 문서 내 용어/표현의 통일성, 스타일 가이드/용어집의 준수 여부, 맞춤법 등을 리뷰하는 과정으로 피어 리뷰(Peer Review)라고도 합니다.
✔️ 퇴고
실제 테크니컬 라이팅 직군의 테크니컬 라이터는 코드 리뷰를 하는 것과 같이 다른 사람에게 문서 검토를 요청하거나 시간을 두고 문서를 다시 본다고 합니다. 시간을 두고 본인의 문서를 보면 또 색다르게 느껴지기 때문에 다시 한 번 검토하는 과정은 굉장히 효과적입니다. 특히 독자 입장에서 읽어보아야 합니다. 코드를 작성하고 며칠 뒤에 다시 보면 ‘어 내가 왜 코드를 이렇게 짰지?’하는 질문을 한번쯤 해봤다면 공감할 수 있을 것 같습니다.
개발 과정에서 QA를 한 번에 거치는 일은 드뭅니다. 개발 과정에서 QA를 여러번 하듯이 문서 검토도 한 번만 하고 끝내지는 않습니다. 한 번 검토한 결과를 주제와 대상 독자부터 문법과 맞춤법까지 다시 검토하고 수정합니다.
아무리 시간이 없어도 검토를 한 번이라도 거치는 것이 중요합니다. 여러 번 볼 수록 문서의 품질은 더 좋아지지만, 일정 등의 여러 리소스를 고려해보면 무작정 검토만 할 수는 없으니 어느 정도 수준있는 문서가 중요하기 때문에 한번이라도 반드시 자기 검토를 해야합니다.
문서는 반드시 대상 독자가 있기 마련인데, 대상 독자와 가까운 동료에서 동료 검토를 받는 것이 좋습니다. 무턱대고 부탁하면 난감할 수 있으니까 동료 검토 점검표를 같이 전달합니다.
5/ Publish
: 문서 배포 / 발행
실제 라인의 테크니컬 라이터의 인터뷰를 확인해보면 문서 배포를 개발 프로세스와 맞춰서 배포 과정을 설계합니다. 초록색으로 표시된 내용이 바로 문서 배포 시점입니다.
✔️ 발행
문서가 종이 책이나 PDF 포맷으로 배포되었던 과거와는 달리, 최근에는 웹 상에 문서를 배포합니다. 웹 배포의 장점은 누구나 쉽게 URL을 통해 문서에 접근할 수 있다는 점이지만, 특정 고객사에게만 배포되어야 하는 문서나 기밀문서의 경우에는 PDF 포맷을 사용하거나 Google Docs 등의 권한 관리 기능을 사용하여 특정 사용자에게만 권한을 부여하는 작업을 하기도 합니다.
문서 배포 이후의 문서 데이터베이스나 버전을 관리하는 곳도 있다고 합니다. 그 이유는 "3년 전에 A 고객사한테 전달했던 그 문서가 필요해요"라는 요구에 당황하지 않고 대응하기 위함합니다.
Reference
🔗 조진호(2012), 이공계 Technical Writing 기본과정 내용에 대한 고찰, Journal of Engineering Education Research
: https://koreascience.kr/article/JAKO201216856525536.pdf
🔗 Google, tech-writing : https://developers.google.com/tech-writing/one
🔗 Technical Writing Process : https://technicalwritingprocess.com/
🔗 개발자들을 위한 테크니컬 라이팅 10계명 : https://tech.kakaoenterprise.com/110
🔗 테크니컬 라이팅 4대 원칙 : https://tech.kakaoenterprise.com/102
🔗 기술 문서 작성 5단계 : https://tech.kakaoenterprise.com/65
'Software Engineering' 카테고리의 다른 글
| 구글이 제안하는, 최적화된 오류 메세지 작성하기 (0) | 2022.12.18 |
|---|---|
| Unit Testing - Software Engineering at Google (0) | 2022.07.07 |
| Documentation - Software Engineering at Google (0) | 2022.06.29 |
| Code Review Flow - Software Engineering at Google (0) | 2022.06.26 |
| A Good Leader - Software Engineering at Google (0) | 2022.06.13 |
Backend Software Engineer
𝐒𝐮𝐧 · 𝙂𝙮𝙚𝙤𝙣𝙜𝙨𝙪𝙣 𝙋𝙖𝙧𝙠