기술적인 글을 잘 쓰려면 기대치를 낮춰야 합니다

기술 글쓰기는 소프트웨어 엔지니어 업무의 중요한 부분이며, 경력이 쌓일수록 그 중요성은 더욱 커집니다. 예를 들어, 수석이나 저명한 엔지니어는 오로지 기술 문서만 작성하기도 하지만, 신입 엔지니어라도 커밋 메시지, 코드 주석, PR 설명 및 댓글, 슬랙 대화, 내부 공지, 문서, 운영 매뉴얼 등 다양한 글을 작성해야 합니다. 글을 잘 쓰는 것과 못 쓰는 것은 매우 큰 차이를 만듭니다.

가능한 한 간결하게 작성하세요

기술 글쓰기의 가장 중요한 원칙은 독자가 거의 관심을 기울이지 않는다는 점입니다. 독자는 보통 첫 문장만 읽고, 다음 문장은 대강 훑은 뒤 나머지는 아예 읽지 않거나 대충 읽곤 합니다. 따라서 가능한 한 짧게 써야 합니다. 아이디어를 한 문장으로 전달할 수 있다면 그렇게 하는 것이 좋습니다. 그러면 실제로 읽힐 확률이 높아집니다.

짧은 문장에 모든 세부사항을 담기 어렵더라도 이는 결함이 아닌 특징입니다. 많은 미묘한 세부사항을 일부러 생략해야 합니다.

이것이 기술 글쓰기와 코드 작성의 가장 큰 차이점입니다. 코드에서는 한 줄 한 줄이 컴퓨터에 매우 중요하지만, 사람에게 말할 때는 주의 집중 시간이 제한적입니다. 예를 들어, 월별 요금이 각 달의 길이 차이를 반영해야 한다면, 코드에서는 한 단락으로 표현해야 하지만, 사람에게 설명할 때는 그런 미묘한 점은 대체로 빼는 것이 현명합니다.

이 때문에 중요한 정보는 앞부분에 배치해야 합니다. 문맥을 설명하거나 서두를 너무 길게 적으면, 많은 독자가 핵심에 도달하기 전에 읽는 것을 멈추거나 대충 읽기 시작합니다. 핵심은 첫 문장에 담으시고, 학술 논문처럼 제목에도 핵심 내용을 넣으면 더욱 효과적입니다.

기대치를 현실적으로 조절하세요

많은 엔지니어가 정보를 일부러 생략하지 않으려 합니다. 그들은 동료들이 꼼꼼히 읽고 완전히 이해할 것이라고 생각하기 때문입니다. 즉, 기술 글쓰기가 할 수 있는 역할에 대해 너무 높은 기대를 하고 있습니다.

기술 글쓰기가 자신의 시스템 이해를 완전히 다른 사람 머릿속에 옮겨줄 수는 없습니다. 오직 기술 시스템과 상호작용하고 코드를 읽으며 고치는 과정에서만 제대로 된 이해가 생깁니다.

좋은 기술 글쓰기는 적어도 대략적인 배경지식을 제공해 독자가 내용을 어렴풋이 이해하게 하며, 최악의 경우에도 글쓴이가 내용을 잘 알고 있다는 점을 독자가 신뢰하도록 돕습니다.

또한 기술 글쓰기가 모두를 완전히 같은 이해 수준으로 만드는 일은 아닙니다. 대규모 조직에서 의견 차이와 혼란이 발생하는 것은 오히려 정상적이며, 복잡한 분산 시스템 내 작은 장애가 일상적인 것과 비슷합니다. 따라서 기술 글쓰기가 이 문제를 해결할 것이라 기대해서는 안 됩니다.

좋은 기술 글쓰기는 무엇을 할 수 있을까요?

좋은 기술 글쓰기는 아주 간단한 기술적 핵심을 넓은 대상에게 전달할 수 있습니다. 예를 들어, “새로운 설정을 추가하려면 데이터베이스 마이그레이션이 필요해서 동적으로 할 수 없다”라는 점을 제품팀에 설명해 불가능한 요구를 막을 수 있습니다. 하지만 실제 전달하는 핵심은 아마도 더 단순할 것입니다. 예를 들어 “설정 추가는 어렵다”거나 “설정이 복잡하다”라는 정도입니다.

이는 기술 글쓰기에 대해 다소 비관적인 시각일 수 있으나, 대규모 조직에서는 이런 제한된 목표조차도 매우 중요합니다. 기술적 혼란도가 워낙 높아 명백한 사실을 전달하는 것조차 큰 효과를 발휘할 수 있기 때문입니다. 엔지니어링 조직을 이끄는 사람들조차도 기술적 배경지식이 많지 않은 경우가 많으며, 이들은 다른 중요한 업무도 많이 신경 써야 합니다.

좋은 기술 글쓰기는 또한 비교적 복잡한 기술 내용을 극소수 대상으로 전달할 수도 있습니다. 예를 들어, 계획된 작업의 세부 사항을 상세히 담은 ADR 문서를 작성해 탁월한 피드백을 받을 수 있습니다. 이런 경우 실제 효과적인 독자는 한 자릿수에 불과할 수 있으며, 때로는 작성자 본인과 관련 맥락을 이해하는 다른 한 명의 엔지니어만이 될 수도 있습니다.

명확하게 생각하기

명확한 글을 쓰려면 우선 명확하게 생각해야 합니다. 이 부분은 별도의 주제이고, 구체적인 조언이 많지 않아 이 글에서는 다루지 않았습니다. 일부 엔지니어에게는 글의 핵심을 한두 문장으로 압축하기 어려운 주된 이유가 명확한 이해가 부족하기 때문입니다. 이들은 여러 관련 아이디어를 나열할 수밖에 없고, 독자가 전체 메시지를 파악하기를 기대합니다.

이와 관련된 글을 약 1년 전 “소프트웨어에 대해 명확히 생각하기”라는 글에서 다루었으며, 그 중 불확실성을 인정하고 확실히 말할 수 있는 부분에 집중하는 내용은 지금도 타당하다고 생각합니다. 다만 이 주제에 대해서는 더 이야기할 것이 많다고 봅니다.

요약

기술 글쓰기에서 엔지니어들이 가장 많이 하는 실수는 기대치를 너무 높게 설정하는 것입니다. 너무 많은 세부 사항을 전달하려다가 결국 아무것도 제대로 전달하지 못합니다. 이는 독자가 핵심에 도달했을 때 이미 관심을 잃었거나, 너무 많은 전제 지식을 기대해 독자가 완전히 혼란스러워했기 때문입니다.

기술 글쓰기는 대부분 작성자보다 기술 배경지식이 부족한 사람들에게 전달하는 것입니다. 작성자는 명확히 이해하고 있지만, 독자는 그렇지 않습니다. 또한 독자는 작성자만큼 주제에 관심이 없고, 만약 다른 팀에 어떤 일을 요청하는 글을 쓴다면, 그 일은 작성자가 관심 있는 프로젝트일지 몰라도 다른 팀은 자신들의 업무에 정신이 팔려 있어 대부분 글을 대충 훑어볼 가능성이 큽니다.

전달하려는 내용을 한 문장으로 말할 수 있다면 그렇게 하십시오. 일부 뉘앙스는 생략해도 됩니다. 한 문단을 써야 한다면 가능한 짧게, 한 페이지를 쓴다면 첫 문단에 핵심 정보를 최대한 담으십시오. 많은 독자가 거기서 멈출 수 있기 때문입니다.

좋은 소식은 전달할 수 있는 내용이 과대평가된 경우가 많지만, 작은 양의 기술 내용을 전달하는 것조차 과소평가되고 있다는 점입니다. 대규모 조직에서는 사실상 전혀 기술적 맥락이 없는 사람이 많은 기술적 결정을 내리는데, 그들에게라도 대략적인 “윤곽”을 전달하는 것만으로도 큰 향상입니다.

---

원문: To get better at technical writing, lower your expectations