소프트웨어 개발자 정준영

Software Engineer

Udemy 기술블로그로 알아보는 테크니컬라이팅 정리및후기

작성일: Sat Dec 23 2023

들어가며

글쓰기 모임 글또를 시작하면서 글을 자주 쓰게 되었다. 모임에서 요구하는 글에 정해진 형식은 없지만, 기술적으로 좋은 글을 쓰고 싶다는 개인적인 욕망이 있었다. 그런데 유데미에서 글또 회원들을 대상으로 무료로 강의를 제공해주셔서, 테크니컬 라이팅 관련 강의를 보게 되었다. 이 글은 해당 강의를 토대로, 나름대로 이해한 바를 덧대어 작성한 글이다.


테크니컬 라이팅의 정의와 특징

테크니컬 라이팅이란 우리말로 직역하면 기술적 글쓰기로, 독자에게 기술적인 정보를 전달하는 것이 목적인 글쓰기를 말한다.

따라서 독자에 따라 다양한 해석이 가능한 문학과는 다르게, 독자가 글을 자의적으로 해석할 여지를 남기지 않아야 한다.

이외의 테크니컬 라이팅과 문학 글쓰기의 차이점은 아래와 같다.

분류 문학 글쓰기 테크니컬 라이팅
내용 창의 사실
대상 일반 특정인
표현 상징 직설
구성 자유 순차

테크니컬 라이팅을 해야 하는 이유

자신이 생각하는 바를 실시간으로 정확히 전달할 수 있으면서, 구두로 논의한 내용을 100% 기억할 수 있는 것이 아니라면 테크니컬 라이팅을 해야 한다고 생각한다. 왜냐하면,

  • 효과적인 의사소통
    • 구두로 생각을 전달하게 되면, 언어적인 표현 외에도 반언어적, 비언어적 표현이 상대방에게 전달되기 때문에 상대방이 의미를 오해하는 경우가 있을 수 있다. 기술적인 내용을 전달할 때에는 팩트 외의 다른 요소들이 팩트 전달에 영향을 끼쳐서는 안된다.
  • 정보 기록과 보존
    • 말, 또는 기억은 쉽게 휘발되지만, 글로 적는 건 휘발되지 않는다.
  • 경쟁력 강화
    • 본인이 터득한 지식과 경험을 공유한다는 것은, 혼자서만 성장하려는 것이 아닌, 주변 사람들의 성장에도 신경을 쓴다는 것을 의미한다. 결과적으로 본인의 경쟁력을 강화하는 결과로 돌아오기도 한다.

기술 문서 작성 프로세스 1. 계획


1-1. 글감 선정

당연한 소리지만, 글을 쓰려면 무슨 글을 쓸지에 대한 고민이 선행되어야 한다. 어떤 글을 쓸지는 작성자 개인의 니즈에 따라 다르겠지만, 글 주제를 좁히기에 어려운 이들을 위한 몇가지 포인트들이 있다.

  • 글을 작성할 때 참고할 양질의 자료를 충분히 찾을 수 있는가

    • 기술 문서를 작성할 때, 가장 중요한 것은 사실을 기반으로 하는 것이다. 때문에 글의 내용을 뒷받침할 만한 자료의 양과 질은 글의 신뢰도를 높이는 데에 도움이 된다.

  • 주제가 충분히 좁은가

    • 한 편의 글을 일정 내에 좋은 품질로 완성하기 위해서는 글의 주제를 좁히는 것이 중요하다.
    수정 전 수정 후
    JavaScript 활용하기 JavaScript 에서 타임존 다루기
    GitHub 사용법 GitHub 를 사용한 효율적인 문서 검토 방법

1-2. 독자 선정

모든 글은 독자가 어느 정도 배경 지식, 혹은 맥락(context)을 갖고 있다는 것을 전제로 작성된다. 따라서 기술 문서를 작성할 때에는 먼저 어느 배경 지식을 가지고 있는 독자를 대상으로 하는 글인지를 분명히 해야 한다. 그렇지 않는다면 글에서 사용되는 모든 용어에 대해 일일이 설명을 덧붙여야 할 것이다. 아래 예시를 보자.

Prerequisites

JavaScript is arguably more difficult to learn than related technologies such as HTML and CSS. Before attempting to learn JavaScript, you are strongly advised to get familiar with at least these two technologies first, and perhaps others as well. Start by working through the following modules:

위 내용은 MDN 자바스크립트 가이드에 있는 내용이다. 자바스크립트는 관련있는 웹 기술인 HTML, CSS 보다 더 어려울 수 있으니, HTML, CSS 에 익숙하지 않은 사람이라면 HTML, CSS 관련 문서를 먼저 읽고 오라는 내용이다.

만약 이러한 배경지식이 없는 사람들도 글의 대상 독자로 선정했다고 가정해보자.

자바스크립트에 관한 기술문서임에도 HTML, CSS 관련 용어가 나올 때마다 해당 용어를 설명하는데에 꽤 많은 지면을 할당해야 할 것이다. 이로인해 자바스크립트만을 학습하러 온 독자는 자신이 원하는 정보를 찾는 데에 애를 먹게 될 것이다.

또, 독자가 선정되지 않았기 때문에 작성자는 기술을 어느 깊이까지 설명해야 할지 감을 잡기가 어렵다.

따라서 기술 문서의 독자를 선정한 뒤 글쓰기에 들어가는 것이 중요하다.


기술 문서 작성 프로세스 2. 초안 작성

글의 주제를 정했다면, 팩트를 전달하는 것이 중요하지, 글의 미관이나 전개 방식등은 사실 별로 중요하지 않다. 따라서 글의 초안을 작성할 때에는 자신있는 부분부터 일단 작성하는 것이 좋다. 글로 적는 것 조차 어렵다면, 우선 머리속에 떠오르는 키워드 부터 나열해보자. 키워드가 이어지면 문장이 되고, 문장이 모이면 단락이 되며, 이것이 곧 문서로까지 이어진다.

이번에는 기술 문서의 초안을 작성할 때 지켜야 할 3C 원칙을 보면서, 좀 더 좋은 초안을 작성할 수 있는 방법에 대해 알아보자.


2-1. 명확 (Clear) 하게

  • 모호함이 없고 확실하게 정확한 내용과 선명한 문장을 사용한다.

  • 수식어보다 명확하고 객관적인 데이터를 사용한다. (매우, 아주, 꽤, 상당히, 괄목할 만하게, 대단히, ...)

  • 링크를 걸 때에는 해당 링크에서 확인할 수 있는 내용을 링크 텍스트로 분명하게 적는다.

  • 수정 전 수정 후
    불과 얼마 전까지만 해도 데이터 센터에 관심이 없었다. LEED Platinum 인증을 받기 전까지 데이터 센터에 관심이 없었다.
    USB 전송 속도가 매우 향상되었다. USB 2.0 의 최대 전송 속도는 초당 35MB 이고, USB 3.0 의 최대 전송 속도는 초당 400MB 이다.
    앱 시작 시간이 너무 길면 알람을 보냅니다. 앱 시작에 2초 이상 걸리면 알람을 보냅니다.
    앞에서 설명한 방법이 유일한 방법이라고 말할 수는 없지 않을까 싶다. 앞에서 설명한 방법이 유일한 방법은 아닐 것이다.
    향후 퀵커머스 산업은 계속 성장할 것이라 판단되는 바입니다. 향후 퀵커머스 산업은 계속 성장할 것입니다.
    새로 나온 '함께 주문' 서비스를 알아보자. 이 서비스를 사용하면 다른 사람들과 장바구니를 공유할 수 있다. 새로 나온 '함께 주문' 서비스를 알아보자. **''함께 주문''**을 사용하면 다른 사람들과 장바구니를 공유할 수 있다.
    오류 코드를 확인하려면 여기를 참고하세요. 오류 코드를 확인하려면 오류 코드 목록을 참고하세요.

2-2. 간결 (Concise) 하게

  • 단문으로 쓴다.

  • 수정 전 수정 후
    나는 사방에서 매미들이 주변의 나무들이 진저리를 칠 정도로 목청을 다해서 발악적으로 시끄럽게 울어대는, 맞은편에서 사람이 오면 비켜설 자리가 없을 정도로 비좁은 오솔길을 혼자 쓸쓸히 걷고 있었다. 나는 오솔길을 걷고 있었다. 혼자였다. 오솔길은 비좁아 보였다. 맞은편에서 오는 사람과 마주치면 비켜설 자리가 없을 정도였다. 매미들이 시끄럽게 울어대고 있었다. 발악적이었다. 주변의 나무들이 진저리를 치고 있었다.

    쉬운 표현을 쓴다.

    수정 전 수정 후
    예약 기능 편의를 제고하고자 익익월 말까지 시스템을 정비할 예정입니다. 예약 기능을 편리하게 사용할 수 있게 다다음 달 말까지 시스템을 정비할 예정입니다.

  • 말하듯 쓴다.

    수정 전 수정 후
    클라우드 상품으로부터 서버 편의성을 제공받을 수 있다. 클라우드 상품을 이용하면 쉽게 서버를 관리할 수 있다.

2-3. 일관 (Consistent) 되게

  • 문서 주제의 일관성 유지 : 같은 주제를 나타내고 있는지 항상 확인할 것

    기존 주제를 잘 지킨 예 (출시 테스트 only) 기존 주제에서 벗어난 예 (출시 테스트 -> 테스트 가이드)
    5월 말 출시 예정인 서비스의 출시 테스트를 진행 중이며, 지금까지 큰 문제는 발견되지 않아 출시 일정에는 문제가 없을 것 같습니다. 자세한 진행 상황은 보고서 페이지를 참고해 주시기 바랍니다. 출시 테스트를 진행하다 보니 테스트 가이드를 보완해야 할 것 같습니다. 테스트 가이드 보완 계획은 이전 메일을 참고해 주세요. 가이드는 다음달 말에 업데이트를 완료할 계획입니다.

  • 형식의 일관성 유지 : 각 문장을 일관성 있게 끝맺음 맺을 것

    수정 전 수정 후
    * 수행 업무 : 타사 사례 리서치
    * 기술 블로그 작성 및 검수 프로세스를 정립한다.    		 수행하는 업무는 다음과 같습니다.
    * 타사 사례 리서치
    * 기술 블로그 글 작성
    * 글 검수 프로세스 정립

  • 용어나 표현을 일관되게 사용한다 : 문서를 여러 명이 쓸 경우, 쓸 용어를 미리 정해둘 것

    네트워크에서 DNS 서버에 액세스해야 하는 인스턴스의 보안 그룹 ID 를 지정합니다. 로드 밸런서에 연결된 시큐리티 그룹에는 instance와 통신할 수 있는 규칙이 있어야 합니다.


기술 문서 작성 프로세스 3. 검토

개발에서 QA 와 디버깅이 제품의 퀄리티를 결정하듯, 작성한 기술 문서가 올바르게 작성되었는지 검토하고 고치는 것이 기술 문서의 퀄리티를 결정한다.

이번에는 기술 문서를 잘 검토하고, 고치는 방법에 대해 알아보자.


3-1. 문서 구조 검토 (MECE)

문서에 빠진 내용이 없는지, 내용 중에 겹치는 것이 없는지 검사할 때 MECE 라는 개념을 주로 사용한다. 이는 Mutually Exclusive, Collectively Exhaustive 의 준말이다. 우리말로 직역하면 ''상호배제와 전체포괄''로, 각 항목들이 상호 배타적이면서 모였을 때는 완전히 전체를 이루는 것을 의미한다. 아래의 예시를 보자.

article_structure_001

서비스 소개 기술문서로 본 MECE 적용 예시 (from. 강의 영상)

  • 1,2 번의 주제인 서비스 특징과 서비스 특장점은 서비스의 특징에 대해 소개한다는 점에서 중복되는 지점이므로, 1. 서비스 특징 으로 묶는다.
  • 3번의 소주제인 연동 서비스와 서비스 이용 방법은 하나의 주제에 묶일 만큼 연관이 있지 않으므로, 소주제를 2. 연동 서비스, 3. 이용 방법 으로 분리한다.

3-2. 자주 보는 문장 오류 검토

문장 오류 종류 수정 전 수정 후
주어와 서술어 미스매치 클라우드 서비스의 장점은 필요할 때 원하는 만큼만 리소스를 사용할 수 있다. 클라우드 서비스의 장점은 필요할 때 원하는 만큼만 리소스를 사용할 수 있다는 점이다.
목적어 생략 툴팁을 보려면 물음표 아이콘 위에 살짝 올려 주세요. 툴팁을 보려면 물음표 아이콘 위에 마우스 포인터를 올려 주세요.
불필요한 말 발송 중에 취소해도 일부 수신자에게는 발송이 진행될 수 있습니다. 발송 중에 취소해도 일부 수신자에게는 발송될 수 있습니다.
불필요한 조사 앱을 종료하려면 홈 메뉴를 클릭을 하고 종료 버튼을 클릭을 합니다. 앱을 종료하려면 홈 메뉴를 클릭하고 종료 버튼을 클릭합니다.
늘어난 말 계획되지 않은 장애로 인하여 서버가 서비스를 제공하지 못하게 되면, 자동으로 장애 조치를 수행합니다. 서버에 장애가 발생하면 자동으로 장애 조치를 수행합니다.
외국어 남용 익월 배포 issue 없게 준비합시다. 새 feature를 추가하는 것보다 performance를 높이는 stance는 유지하고요. 관련 부서에도 wording 다듬어서 quick하게 comm. 해주세요. 익월 배포 문제 없게 준비합시다. 새 기능을 추가하는 것보다 성능을 높이는 입장은 유지하고요. 관련 부서에도 내용 다듬어서 빠르게 협의 해주세요.
  • 외국어보다 우리말을 사용한다
    • 외국어 대신 사용할 수 있는 우리말을 찾아본다.
    • 적당한 우리말이 없다면 음차해서 사용한다. (server -> 서버)
    • 특정 분야 전문 용어라면 원문을 병기한다. -> 텐서(tensor)는 배열이나 행렬과 매우 유사한..
    • 타사 서비스나 제품 이름인 고유명사는 원문 그대로 쓴다. (Microsoft Azure || Adobe Acrobat)

3-3. 용어 검토

대상 독자를 선정했음에도 불구하고, 문서에서 사용하는 모든 용어를 대상 독자가 이해하기는 어려울 수 있다. 따라서 아래의 조건에 해당하는 용어에 대해서는 적절한 설명을 추가해주는 것이 바람직하다.

  • 특정한 개념으로 정의된 단어

  • 절대적인 의미를 갖는 단어 (분야에 따라서 용어의 의미가 다를 수 있으므로)

  • 단어를 줄여 쓴 약어


3-4. 단락 길이 검토

단락이 너무 길면 글이 지루하게 보이기 마련이다. 따라서, 하나의 단락은 중심 생각 하나만 담는 것이 중요하다. 개발에서 함수 하나가 여러 역할을 하면 디버깅과 코드 리딩이 어려워지는 것과 같다.


3-5. Semantic Symbol 사용 검토

글에 사용되는 다양한 심볼들은 그 의미와 원래의 용도에 맞게 사용해야 글의 가독성을 높일 수 있다.

  • 목록
    • 점 목록 : 순서에 관계없는 동등한 항목을 나열
    • 숫자 목록 : 순서가 있는 동등한 항목을 나열
  • 시각 자료 사용
    • 스크린샷 : 사물의 생김새를 보여줄 때
    • 그래프 : 수나 양을 표현할 때
    • 다이어그램 : 구조, 관계 등의 논리적인 흐름을 나타낼 때
    • 표 : 항목을 비교하거나 정리할 때
    • 시각 자료 앞에 설명을 놓을 것
    • 글에서 언급하기 쉽도록, 시각 자료에 제목을 달 것

3-6. 보안 검토

글이 외부에 공개되어서는 안되는 내용을 담고 있지는 않은지 검토해봐야 한다.


4. 추가 팁

기술 문서는 사실에 기반해 내용을 정확하게 전달하는 것이 가장 중요하다. 그러나 독자들이 내가 쓴 글을 계속 읽고 싶게 하는 소프트한 문서 작성 스킬 역시 중요하다. 이번에는 독자들이 조금 더 글에 흥미를 갖고, 원하는 정보를 얻어갈 수 있게끔 해주는 방법에 대해 알아보자.


4-1. 도입부 작성 요령

글의 도입부는 독자로 하여금 글을 계속 읽어야 할 동기를 부여하거나, 흥미를 돋구는 역할을 한다. 이 때 효과적인 방법들을 소개한다.

  • 질문으로 먼저 시작
    • 독자에게 질문을 던짐으로써 글의 전개에 적극적인 참여자로 개입하게 한다.
  • 용어나 개념 정리로 시작
    • 다소 클래식한 방법으로, 글에서 사용할 용어나 개념에 대해 간단히 정리함으로써 독자의 배경 지식을 기술 문서를 이해하기에 적합한 수준으로 끌어올려 준다.
  • 나만의 경험 서술로 시작
    • 저자만의 개인적인 경험은 독자로 하여금 저자가 좀 더 친근한 인물처럼 느껴지게끔 한다.
  • 유명한 인물이 썼던 문장을 인용하면서 시작
    • 유명한 인물의 문장과 글의 주장이 서로 연관이 있음을 은연중에 드러냄으로써, 유명인이 가지고 있는 신뢰 자산을 빌려와 글의 신뢰도를 높일 수 있다.

4-2. 개요 작성 요령

개요는 주로 도입부 직후에 나오는 것으로, 본격적으로 글을 시작하기에 앞서 글에 대해 좀 더 포멀한 소개를 하는 부분이다. 독자는 개요를 읽고 어떤 글을 읽게 될 지 파악할 수 있다.

  • 글에서 다루는, 다루지 않는 주제
    • 글의 제목과 도입부는 글이 담고 있는 내용을 다소 함축적으로 보여주거나 과장하는 부분이 있다. 따라서 독자들에게 이 글이 실제로 어떤 내용을 다루는지, 또는 다루지 않는지 분명히 해야 독자와 저자간의 오해를 줄일 수 있다.
  • 대상 독자
    • 이 글이 어떤 배경지식, 혹은 맥락을 가진 독자를 대상으로 하는지 분명히 해야 한다. 이를 통해 저자는 글의 본문에서 언급하지 않은 맥락에 대해 설명하지 않아도 되므로 더 깊은 이야기를 지면에 할당할 수 있고, 독자들은 불필요한 시간 낭비를 줄일 수 있다.
  • 글을 읽고 독자가 알 수 있는 것
    • 글을 읽으면 어떤 정보를 얻어갈 수 있는지 독자에게 미리 인지시켜 준다. 이를 통해 독자는 자신이 글에 대해 기대하는 바와 글의 내용이 실제로 일치하는지 미리 가늠해볼 수 있다.
  • TL:DR
    • Too Long: Did not Read 의 준말로, 대부분의 기술 문서는 내용이 복잡하고 긴 경우가 많으므로, 본문의 내용을 최대한 요약하여 제공하는 요약문이다. 바쁜 독자들은 본문을 훑어가며 요약하지 않고, 이 부분만 읽으면 되므로 시간을 절약할 수 있다.

후기

강의 중 나왔던 내용 중 ,글쓰기가 어려운 이유에 대해 'write to express, not impress' 라는 표현이 나왔다. 인상을 남기기 위해 글을 쓰지 말고, 표현하기 위해 글을 쓰라는 문장이다. 이 문장을 보고 나니 그동안 나는 독자에게 어느정도 인상을 주어야 한다는 생각을 하고 있었던 것 같다. 그래서 글을 쓰는 속도가 느렸고, 아웃풋이 없으니 결과적으로 글을 쓰고 싶다는 생각도 줄어들었다. 앞으로는 글을 쓸 때 독자에게 인상을 주려고 하기보다는, 내가 알고 있는 것과 공부한 것, 느낀 점등을 온전히 표현하는 데에 집중해보기로 했다.


레퍼런스

https://www.udemy.com/course/techwriting/

해당 콘텐츠는 유데미로부터 강의 쿠폰을 제공받아 작성되었습니다.