4.5 KiB
name, description
| name | description |
|---|---|
| revising-korean-technical-prose | Use when a Korean technical blog or reader-facing document should read like a first-person experience or retrospective, especially when settled facts are buried under abstract, formulaic, translated, or AI-generated prose. |
Revising Korean Technical Prose
핵심 원칙
기술 사실을 설명문으로 나열하지 말고, 작성자가 직접 코드를 보고 실행하면서 예상하고, 발견하고, 판단하고, 바꾼 과정으로 쓴다. 논리와 근거는 그대로 두고 서술 관점과 문장 형식만 고친다.
문장 패턴을 처음부터 끝까지 읽은 뒤 수정한다.
경험담 문체
문서의 시작과 주요 전환에서는 저는이나 제가를 사용한다. 모든 문장에 반복하지는 않는다. 다음 흐름으로 문단 전체를 다시 쓴다.
- 처음 마주한 코드, 화면, 요청 또는 문제를 보여 준다.
- 당시의 예상이나 처음 보인 인상을 짧게 적는다.
그런데뒤에 실제 실행이나 코드 추적에서 발견한 차이를 둔다.- 낯선 용어는 그때 이해한 내용처럼 바로 풀어 쓴다.
- 그 차이 때문에 무엇을 확인하고 선택하거나 바꿨는지 적는다.
- 결과와 함께 새로 생긴 비용이나 남은 문제를 적는다.
여섯 요소의 이름은 출력하지 않고 필요한 요소만 쓴다. 독자가 작성자의 확인 순서를 따라가게 하며, 기준 문단이 ~했습니다를 사용하면 같은 높임말을 유지한다.
첫 번째 제약이다를 지우거나 호출 주체를 구성요소 이름으로 바꾸는 것만으로는 교정이 끝나지 않는다. 처음에는, 그런데 확인해 보니, 그래서, 그 결과로 이어지는 경험의 흐름이 보여야 한다.
한국어 말하기 검사
소리 내어 읽고 한국인 개발자가 동료에게 할 말인지 확인한다. 번역은 맞지만 실제로 말하지 않을 표현이면 다시 쓴다.
대조할 때는 겉으로 보이는 것 → 실제 동작을 바로 연결한다.
화면에서 보이는 이름은 같지만 실제 검증 방식은 다릅니다.
이름을 믿는 이유, 위치와 모양, 의미와 관점처럼 추상적인 말을 대조의 결론으로 두지 않는다. 실제로는 뒤에 JWT 검증, header 확인, token 저장처럼 코드에서 일어나는 차이를 쓴다. 같지만, 달랐습니다, 이유를 금지어로 찾지 말고 문장이 실제 대상을 바로 말하는지 확인한다.
경험과 사실의 경계
코드 비교, 실행, 요청 추적처럼 실제로 수행한 작업은 1인칭으로 서술할 수 있다. 사용자가 경험담 문체를 요구했다면 이 관점을 제거하지 않는다.
다만 근거에 없는 감정, 대화, 조언, 실패, 성과, 작업 기간은 만들지 않는다. 놀랐습니다, 누군가 조언했습니다, 며칠이 걸렸습니다처럼 확인할 수 없는 경험은 추가하지 않는다. 기술 선택의 이유도 새로 만들지 않는다.
다음 항목은 그대로 보존한다.
- 제목과 절의 순서, 주장, 선택 이유, 대안, 비용, 가드레일, 근거 범위
- 숫자, 버전, 식별자, 코드, 명령, 표, 링크, 다이어그램, 의도한 분량
- 현재 동작, 테스트가 확인한 동작, 아직 확인하지 않은 동작의 차이
문장 순서와 문단 구분은 경험의 흐름을 만들기 위해 조정할 수 있다. 논리, 사실성, 분량, 다이어그램과 정보 구조는 다시 평가하지 않는다.
수정 절차
- 앞뒤 문단까지 읽고 작성자가 실제로 확인한 코드, 실행 결과와 판단을 찾는다.
- 독자가 경험을 따라갈 시작점과
그런데뒤에 놓을 발견을 고른다. - 주요 절을 1인칭 경험으로 열고, 기술 동작은 구체적인 구성요소와 동사로 설명한다.
- 낯선 용어를 처음 필요한 문장 옆에서 풀어 쓴다.
- 대조 문장은 소리 내어 읽고
실제로는 무엇이 다른가에 바로 답하는지 확인한다. - 파일을 직접 수정한 뒤 사실, 조건, 불확실성이 바뀌지 않았는지 비교한다.
완료 조건
- 작성자의 시작점, 발견, 행동과 결과가 보인다.
- 단순한 객관식 해설이나 결론 목록으로 읽히지 않는다.
- 필요한 곳에서
저는이나제가가 실제 서술 관점을 만든다. - 한국인 개발자가 동료에게 설명할 때 쓸 수 있는 문장으로 읽힌다.
- 기술적 의미와 문서 구조가 그대로 남는다.