writing

번역투를 걷어낸다

이 저장소의 문서는 한국어가 기본이다. 그런데 영어로 생각한 문장을 그대로 옮기면 뜻은 통하는데 읽는 속도가 떨어진다. 아래는 실제로 이 저장소의 문서에서 걷어낸 사례다.

어디에 적용하는가

한국어로 쓰는 모든 글에 적용한다. 파일에 쓰는 것만이 아니다.

무엇	예
채팅 답변	작업 도중의 설명, 요약, 되묻는 질문, 선택지 제시
저장소 문서	README, CONTRIBUTING, CHANGELOG, 튜토리얼, 스킬과 에이전트 프롬프트
생성되는 설계 문서	concept.md, ruleset.md, 검토 리포트, 플레이테스트 기록, 아트 바이블
부산물	커밋 메시지, PR 본문, Issue 본문, 코드 주석

대화가 특히 티가 난다. 문서는 나중에 다시 읽으며 고칠 수 있지만 답변은 그대로 남는다. 길게 쓸 때보다 급하게 요약할 때 「~하는 것입니다」와 「~할 수 있습니다」가 몰린다. 답변을 내보내기 전에 그 두 어미가 문단마다 반복되는지 한 번 본다.

문장을 명사로 끝내지 않는다

The lesson here is that ..., The point is that ... 을 옮기면 「~는 것입니다」가 된다. 문장 하나에 한 번은 괜찮지만 문단마다 나오면 글이 늘어진다.

안 좋음: 여기서 얻을 교훈은 단일 컬럼 이상치 탐지로는 코스트 대비 문제를 못 잡는다는 것입니다.
좋음:   한 컬럼만 들여다보면 코스트 대비 문제는 안 잡힙니다.

하려는 말을 서술어로 끝내면 대개 짧아진다. 「~라는 뜻입니다」, 「~인 셈입니다」도 같은 부류이므로 문단에 하나로 제한한다.

설명을 덧붙여 마무리하지 않는다

That is why ..., That is the important part here 계열이다. 한국어에서는 앞 문장이 이미 이유를 말하고 있어서 덧붙이면 같은 말을 두 번 하게 된다.

안 좋음: 이걸 인쇄 전에 아는 것과 인쇄 후에 아는 것의 차이가 이 도구의 존재 이유입니다.
좋음:   인쇄하고 나서 알면 늦습니다.

안 좋음: 선택지를 제시하고 멈추는 게 여기서 중요한 부분입니다.
좋음:   여기서 도구가 멈춰서는 게 중요합니다.

읽는 사람을 3인칭으로 부르지 않는다

문서는 읽는 사람에게 직접 말하는 글이다. 그 사람을 「사용자」라고 부르면 남 얘기가 된다. 「사용자」는 시스템을 설명할 때만 쓰고, 읽는 사람을 가리킬 때는 쓰지 않는다.

안 좋음: 도구가 알아서 잘라버리면 사용자는 자기 컴포넌트가 바뀐 걸 모릅니다.
좋음:   알아서 잘라버리면 내 컴포넌트가 바뀐 줄도 모르고 넘어갑니다.

에이전트가 사용자에게 결정을 넘기는 대목처럼 역할을 지칭해야 할 때는 그대로 쓴다.

어미를 섞지 않는다

한 절 안에서 시키는 문장과 설명하는 문장의 어미가 번갈아 나오면, 따라 하는 사람이 지금 무엇을 해야 하는지 헷갈린다. 시키는 문장은 ~하세요, 결과를 설명하는 문장은 ~합니다로 갈라놓는다. 「~해주세요」는 부탁이므로 절차에는 쓰지 않는다.

안 좋음: 값을 바꿉니다. 다시 돌려서 출력을 읽어주세요. 그다음 되돌립니다.
좋음:   값을 바꾸세요. 다시 돌리면 출력이 이렇게 바뀝니다. 확인했으면 되돌리세요.

습관으로 쓰는 표현을 덜어낸다

• 「~할 수 있습니다」 — 가능성을 말할 때만 쓴다. you can run it 은 대개 「돌립니다」다
• 「~이 필요합니다」 — X is needed 다. 버전이나 준비물을 말할 때만 쓰고, 시켜야 하는 말이면 ~하세요 로 바꾼다. 「세 칸이 전부 필요합니다」가 아니라 「셋을 다 적으세요」다
• 「~에 대해」 — about 의 직역이다. 「~를」로 끝나는 경우가 많다
• 「~되어집니다」, 「~보여집니다」 — 피동을 두 번 겹친 것이다
• 「이것」, 「그것」 — 무엇을 가리키는지 이름으로 쓰면 다시 읽을 일이 없다
• 「가장 ~한 것 중 하나」 — one of the most 다. 최상급이 아니면 그냥 「~한 편이다」