[26.11.02] 학습: 목표와 이유가 드러나도록 글 다듬기

AI와 글을 다듬으면서도 고민은 남았습니다. 문장은 자연스러워졌는데 무엇을 설명하려는 글인지 알기 전에 구현과 수치부터 읽어야 하는 경우가 있었습니다. 누가 읽을지와 함께, 목표부터 세부 설명까지 어떤 순서로 보여줄지 생각할 필요가 있었습니다.

이 고민을 풀기 위해 글쓰기 책과 기술 문서 가이드를 참고했습니다. 자료에서 어떤 관점을 가져왔고, 제 글에 적용하면서 무엇이 달라졌는지 돌아보려고 합니다.

책과 글에서 가져온 기준

목표에서 세부 설명으로 내려가며 글 구성하기

유영경의 『개발자를 위한 글쓰기 가이드』에서는 다음 원칙을 참고했습니다. 관련 항목은 출판사가 공개한 목차에서 확인할 수 있습니다.

• 누가 읽는지에 맞춰 기술 설명의 깊이를 조절합니다.
• 핵심을 먼저 써서 글의 요점을 드러냅니다.
• 한 문장에는 주제 하나를 담고, 용어와 약어는 독자가 이해할 수 있도록 풀이합니다.
• 내용에 맞는 시각 자료를 고릅니다. 비교에는 표를 쓰고, 데이터의 성격에 맞춰 차트를 선택합니다.

제게 도움이 된 것은 읽는 사람이 무엇을 먼저 알아야 하는지 생각하는 관점이었습니다. 이를 제 글에서는 추상화 수준에 따라 내용을 배치하는 방식으로 확장했습니다. 목표와 이유를 먼저 설명하고, 아래로 갈수록 구조와 동작, 구체적인 구현과 수치로 내려갑니다.

개별 함수나 설정을 먼저 소개하기보다, 그 내용을 왜 살펴봐야 하는지부터 설명하려고 했습니다. 같은 질문에 답하는 독립된 내용은 불릿이나 표로 묶었습니다. 문제에서 선택과 결과로 이어지는 인과관계는 문단으로 연결하고, 추상화 수준이 달라지는 곳은 소제목과 연결 문장으로 구분했습니다.

이렇게 배치하니 세부 정보를 어디에 둘지도 정하기 쉬워졌습니다. 목표를 설명하는 문단에 섞여 있던 구현 내용은 아래로 옮기고, 목표나 선택 이유와 연결되지 않는 내용은 덜어냈습니다. 제목과 본문, 그림도 해당 부분에서 다루는 설명 수준에 맞췄습니다.

같은 개념에는 같은 단어 쓰기

Google의 기술 문서 문체 가이드와 용어 일관성 기준에서는 다음 내용을 참고했습니다.

• 자연스럽고 직접적인 표현으로 대상과 행동을 적습니다.
• 상투적인 표현과 반복되는 문장 시작을 피하고, 앞뒤 연결을 살펴봅니다.
• 같은 개념에는 같은 단어를 씁니다. 표현이 달라져 다른 개념으로 읽히지 않도록 용어를 통일합니다.

AI가 고친 문장도 이 기준으로 다시 읽었습니다. “요청 수”를 “요청량”이나 “호출 수”로 바꾸면 같은 지표인지 다시 생각해야 했습니다. 다만 “전체 요청 수”와 “성공 요청 수”는 다른 지표이므로 구분해야 합니다. 용어를 통일하기 전에 가리키는 대상이 같은지 확인하는 것이 먼저였습니다.

문장을 고칠 때는 대상과 조건도 함께 확인했습니다. 아래는 그 기준을 연습하기 위한 예시입니다.

마지막 예시는 응답 구성을 확인하지 못한 상황입니다. 수치를 확인했다면 그 값을 적습니다. 문장을 줄이더라도 확인한 사실과 추정이 뒤섞이지 않는지 살펴보게 됐습니다.

초안을 고칠 때 구체적인 질문 던지기

GeekNews에 소개된 글의 원문인 Gergely Orosz의 Becoming a Better Writer에서는 다음 관점이 도움이 됐습니다.

• 초안에는 전달할 생각을 담고, 편집할 때 독자가 따라갈 수 있는 순서인지 다시 읽습니다.
• 한 문단에는 생각 하나를 담고, 불필요한 설명과 긴 문장을 줄입니다.
• 피드백을 요청할 때는 이해하기 어려운 부분이나 불필요한 내용을 구체적으로 묻습니다.
• 도구의 제안도 글의 의미와 문체에 맞는지 판단합니다. 제안이 잘못됐거나 글에 맞지 않으면 받아들이지 않습니다.

이 관점을 AI와 글을 고치는 상황에 적용한다면, 한 번에 모든 것을 고치기보다 검토할 질문을 나눌 수 있습니다.

오늘 글도 처음에는 편집 규칙과 AI 요청문을 길게 나열했습니다. 제 고민과 달라진 점이 빠졌다는 것을 확인하고, 참고 자료와 적용 사례를 중심으로 고쳤습니다. 문장을 고치기에 앞서 글의 목적과 구성을 다시 살펴야 한다는 점을 느꼈습니다.

같은 기준도 글의 목적에 맞게 적용하기

글 전체의 순서와 함께, 목적에 따라 강조할 내용도 구분하고 있습니다.

보고서에서는 결론과 판단 근거를 앞에 두기

보고서는 결론과 판단 근거를 쉽게 찾을 수 있도록 다음 기준으로 정리해 사용하고 있습니다.

• 앞부분에는 무엇을 판단하려는지와 결론, 결정이 필요한 사항을 적습니다.
• 본문에는 확인한 결과와 판단 근거를 담습니다.
• 뒷부분에는 상세 수치와 운영 정보를 모읍니다.

내용을 줄일 때는 “이 문장이 없으면 판단이 달라지는가”를 묻고, 판단에 필요한 설명은 남깁니다.

회고에서는 선택 이유와 달라진 점을 설명하기

기술 경험 회고에서는 무엇을 확인하려 했고 왜 그 동작을 살펴봤는지 먼저 설명했습니다. ArrayList 확장과 GC를 비교한 글에서는 확장에 필요한 공간과 객체가 이동하는 조건을 확인하려 했습니다. 원소 추가와 내부 배열 교체, GC를 한꺼번에 설명하면 복사와 이동을 구분하기 어려웠습니다.

그래서 배열과 객체의 관계를 설명한 뒤 각 동작과 관측 결과로 내려가도록 구성했습니다.

• 배열 확장에서는 새 배열에 참조값을 복사하는 과정을 설명했습니다.
• GC 분석에서는 Heap과 Region을 소개한 뒤 객체 주소를 비교한 결과를 배치했습니다.

설명을 나누면서 “배열을 복사한다”는 표현도 무엇을 복사하는지 구체적으로 고칠 수 있었습니다. 세부 필드 이름은 필요한 코드에 남기고, 본문에서는 “내부 배열”처럼 역할로 풀어 썼습니다.

시각 자료를 고르는 관점은 사내 버셀을 Spring으로 통합한 글에 적용했습니다. 현재 바뀐 부분과 앞으로 바뀔 부분을 구분하려고 두 그림을 나눴습니다.

• Control API만 교체한 그림에서는 나머지 서비스가 유지되는 범위를 보여줬습니다.
• 전체 전환이 끝났을 때의 그림에서는 최종적으로 통합할 구조를 보여줬습니다.

설명할 내용에 따라 표현 방식도 나눴습니다.

그림에 나온 구조를 본문에서 반복하는 설명을 줄이면서 선택 이유를 더 집중해서 다룰 수 있었습니다.