7.6 KiB
한국어 기술문서 문장 패턴
기준이 되는 문장
처음 Claude와 만든 코드는 Python이라는 언어로 짜여 있었습니다. 그런데 "Java나 Kotlin으로 포팅한 뒤 베타 배포하면 작업을 두 번 하지 않아도 된다"라는 조언을 받았습니다. 포팅이 뭔지 그때는 몰랐지만 코드를 다른 언어로 옮겨 다시 만드는 일이라고 합니다. 사내 표준이 Kotlin이니 어차피 옮길 거라면 지금 옮기라는 뜻이었습니다. 듣기엔 큰 작업 같은데 제가 한 일은 Claude에게 "FastAPI 대신 Kotlin과 Spring Boot로 바꿔 줘"라고 요청한 것뿐이었습니다. FastAPI는 Python으로, Spring Boot는 Kotlin으로 서버를 만들 때 쓰는 도구입니다. 이 문장 하나로 언어도 도구도 모두 바뀌었습니다.
이 문단을 문장 형식과 서술 관점의 기준으로 삼는다. 제가를 빼고 객관적인 설명문으로 바꾸면 안 된다. 독자가 기술을 배우는 동시에 작성자가 문제를 만나고 이해하고 행동한 순서를 따라갈 수 있어야 한다.
- 처음에는 독자가 바로 그릴 수 있는 사람, 코드, 화면 또는 상황을 보여 준다.
- 그다음 실제로 생긴 문제나 달라진 조건을
그런데,다만,그래서처럼 익숙한 말로 잇는다. 포팅처럼 독자가 모를 수 있는 말은 처음 필요한 자리에서 짧게 설명한다.- 조언이나 제약이 실제로 무슨 뜻인지 일상적인 문장으로 한 번 풀어 쓴다.
- 판단, 행동, 결과를 한 문장에 압축하지 않고 차례로 보여 준다.
- 짧은 문장과 긴 문장을 섞되, 일부러 구어체를 만들지는 않는다.
- 작성자가 직접 확인하고 실행하고 바꾼 일은
저는과제가를 사용해 경험으로 쓴다. - 근거에 없는 감정, 대화, 조언과 성과를 만들어 경험담을 꾸미지는 않는다.
문단 전체를 다시 쓰는 예시
수정 전:
화면과 최종 값만 보면 네 구현은 같은 일을 하는 것처럼 보인다. 그런데 최초 입력부터 최종 출력까지 따라가 보면 code와 token을 다루는 곳도, API를 실제로 부르는 곳도 패턴마다 다르다.
수정 후:
처음 네 예제를 실행했을 때는 모두 로그인 뒤 같은 사용자 JSON을 보여 주었습니다. 그래서 처음에는 Keycloak을 연결하는 방법만 네 가지로 나눈 것처럼 보였습니다. 그런데 브라우저의 network 요청을 처음부터 따라가 보니 code와 token이 머무는 곳이 서로 달랐습니다. Authorization code는 로그인을 마친 사용자가 애플리케이션으로 돌아올 때 잠시 들고 오는 교환용 값입니다. 이 값을 access token으로 바꾸는 곳부터 확인했습니다. AP1에서는 브라우저가 직접 바꾸었고, AP2와 AP3에서는 Spring server가 바꾸었습니다. AP4에서는 oauth2-proxy가 같은 일을 맡았습니다. 화면은 같지만 실제 token 처리와 API 호출 방식은 다릅니다.
여기서는 호출 주체가 다르다를 구성요소 이름으로 바꾸는 데서 멈추지 않는다. 작성자가 같은 화면을 보고, 예상과 다른 요청을 발견하고, 낯선 값을 이해한 뒤, 각 구성요소를 확인한 순서로 문단 전체를 다시 쓴다.
작성자와 외부 분석자를 바꾸지 않는다
사용자가 자신이 만든 코드를 설명한다면 다음 문장은 관점이 잘못됐다.
수정 전:
처음 저장소를 열었을 때 19개 모듈이 먼저 보였습니다. 각 빌드 파일을 따라가 보니 코어의 클래스패스를 제한하는 구조였습니다.
수정 후:
코어에서 금지한 프레임워크 타입이 보이지 않게 하려고 클래스패스를 모듈마다 나눴습니다. 선택형 어댑터까지 분리한 결과 19개 모듈이 됐습니다.
작성자는 자신의 코드를 열어 보고, 훑어 보고, 따라가며 발견한 사람처럼 말하지 않는다. 만들 때 해결하려 한 문제, 정한 기준, 구현한 방법, 아직 연결하지 않은 범위와 받아들인 비용을 설명한다. 반대로 소유 관계를 알 수 없는 문서에 작성자 경험을 새로 붙이지 않는다.
한국어에서는 실제 차이를 바로 말한다
수정 전:
화면에 찍힌 이름은 같았지만 그 이름을 믿는 이유는 달랐습니다.
수정 후:
화면에서 보이는 이름은 같지만 실제 검증 방식은 다릅니다. AP1은 JWT의 서명과 issuer, audience를 확인하고, AP4는 edge를 거친 header와 internal token을 확인합니다.
수정 전 문장은 뜻은 통하지만 한국인 개발자가 동료에게 설명할 때 잘 쓰지 않는 대조다. 믿는 이유를 한 번 더 해석하게 하지 말고 실제로 다른 검증 방식을 바로 쓴다.
다음 문장도 같은 기준으로 고친다.
| 어색한 표현 | 자연스러운 방향 |
|---|---|
| 위험의 위치와 모양이 바뀌었습니다 | token을 옮길 때마다 session 저장소나 header 검증 같은 다른 문제가 생겼습니다 |
| 두 값의 의미는 달랐습니다 | 하나는 JWT claim이고 다른 하나는 Nginx가 만든 header입니다 |
| 보안 등급표가 아니었습니다 | 번호가 높다고 더 안전한 구조는 아니었습니다 |
고쳐 쓰는 방법
추상적인 주체
수정 전:
네 시스템은 서로 다른 credential과 서로 다른 호출 주체를 사용한다.
수정 후:
AP1과 AP2에서는 브라우저가 API를 직접 부릅니다. AP3에서는 BFF가 대신 호출하고, AP4에서는 Nginx가 요청을 이어 갑니다.
호출 주체가 다르다고 분류하지 말고 실제 구성요소와 행동을 쓴다.
개요를 읽어 주는 서수
수정 전:
구현되지 않은 운영 속성을 추론하지 않는 것이 첫 번째 제약이다.
수정 후:
그래서 패턴 이름만 보고 구현되지 않은 운영 속성을 덧붙이면 안 됩니다.
실제 순서를 뜻하지 않는 첫 번째, 두 번째, 마지막은 제거한다. 절차, 화면, 레이어처럼 순서 자체가 정보라면 유지한다.
의미 분류명을 반복하는 문장
수정 전:
상황은 브라우저 호출을 유지해야 하는 경우다. 선택은 confidential mediator다.
수정 후:
브라우저가 Resource Server를 직접 부르는 방식은 유지해야 했습니다. 다만 client secret과 refresh token까지 JavaScript에 맡길 수는 없었습니다. 그래서 code 교환과 refresh token 보관은 confidential mediator가 맡았습니다.
상황, 선택, 대안, 가드레일을 주어로 삼지 않는다. 그 자리에 요구, 행동, 이유, 남은 비용을 넣는다.
낯선 용어
용어를 삭제하거나 모두 번역하지 않는다. 처음 이해가 필요한 지점에서만 짧게 푼다.
포팅은 코드를 다른 언어로 옮겨 다시 만드는 일입니다.
authorized client는 로그인한 사용자와 OAuth client에 연결된 token 묶음입니다.
뒤 문장에서 이미 행동으로 뜻이 드러나면 별도의 정의를 반복하지 않는다.
AI처럼 보이기 쉬운 신호
다음 표현을 금지어로 취급하지 않는다. 문단의 구체적인 행동을 대신하고 있을 때만 고친다.
관점,측면,구조,주체,경계,맥락이를 통해,이러한,해당,~하는 것이 중요하다상황은,선택은,대안은,비용은,가드레일은- 실제 순서가 없는
첫 번째,두 번째,마지막으로 - 같은 길이와 어순으로 반복되는 세 문장
고친 뒤에도 기술적 정확성에 필요한 용어와 구분은 남겨 둔다.