제가 편집할 때 생각하는 것들 (2019)

• 편집은 문장을 다듬기 전에 글이 실제로 말하려는 바와 독자를 확인하는 작업이며, 이메일·문서·블로그·소설에도 같은 기본 원칙을 적용할 수 있음
• 글의 시작과 끝에서 핵심을 다시 짚고, “this/that” 같은 지시어 대신 명사를 붙이면 독자가 문맥을 놓치지 않아 명확성이 높아짐
• 불필요한 단어를 줄이고, 지시문은 명령형으로 바꾸며, 긴 문장과 “of/for” 구조를 쪼개면 의미가 더 빨리 전달됨
• 수동태·부사·전문용어·상투어는 행위자와 정확한 의미, 독자 범위를 흐릴 수 있으므로 구체적인 동사와 설명으로 바꾸는 편이 좋음
• 좋은 편집은 규칙을 맹목적으로 따르는 일이 아니라, 전달하려는 메시지에 맞게 언어 선택을 의식하고 불필요한 표현을 제거하는 일임

---

글이 실제로 말하는 바부터 정하기

• 문장 단위 편집에 들어가기 전에, 글이 의도한 바를 실제로 말하고 있는지 먼저 확인해야 함
• 글마다 개인용 프리앰블(preamble) 을 써두면 편집 기준이 생김
  • 핵심 질문은 “주요 요점은 무엇인가”, “누구를 위해 쓰는가”임
  • 이 정보를 문서 맨 위에 적어두고, 작성·편집 중 실제 내용과 비교함
• 블로그 글의 요점을 한두 문장으로 요약할 수 없다면, 일관된 글을 쓰기 어려움
• Writers Studio의 창작 수업에서는 과제마다 의도한 화자, 톤, 분위기를 포함한 프리앰블을 쓰고, 평가는 취향보다 기법과 의도 달성 여부에 초점을 둠

반복은 독자를 붙잡아 주는 장치

• 핵심이 충분히 분명해 보여도, 글의 시작과 끝에서 다시 말하면 독자가 요점을 더 잘 따라올 수 있음
• 문서 튜토리얼은 보통 무엇을 할지 소개하고, 절차를 제공한 뒤, 제대로 수행했는지 검증하는 구조가 좋음
• 블로그 글도 다룰 주제를 소개하고, 본문에서 전개한 뒤, 끝에 짧은 요약을 두는 방식이 적합함
• 언어 수준에서도 반복이 필요함
  • 지시대명사인 “this”, “that”만 쓰지 말고, 무엇을 가리키는지 명사를 붙임
  • “To solve this”보다 “To solve this shortage”가 더 명확함
  • “That will take you to the home screen”보다 “Successfully authenticating will take you to the home screen”이 더 분명함
• 작성자에게는 반복처럼 느껴져도, 독자에게는 글을 따라가기 쉽게 만드는 명확화가 됨

단순화: 의미 없는 단어 덜어내기

• 편집에서 가장 중요한 작업은 의미에 기여하지 않는 단어를 제거하는 것임
  • “You will need to run this script”는 “Run this script”로 줄일 수 있음
  • “You can aid in readability by making sure…”는 “Make sure…”로 줄일 수 있음
• 특별한 이유가 없다면 가능한 한 빨리 요점에 도달해야 하며, 과도한 단어와 장식적인 문장 구조에 의미를 묻지 않아야 함

• 지시문은 명령형으로 바꾸기

  • 지시문에서 “You should X”, “You can X”는 동사의 명령형으로 바꾸는 편이 간결함
  • “You should save the file to your home directory”는 “Save the file to your home directory”가 됨
  • 이 변화는 단어 수를 줄이고 독자를 바로 행동으로 이끎

• “of”와 “for” 구조 줄이기

  • “of”나 “for”가 이어지는 구조는 명사 앞에 정보를 배치하도록 다시 쓰면 더 효율적임
  • “The manager of the team responsible for marketing”은 “The marketing team’s manager”가 됨
  • 재배치된 문장은 독자가 절마다 이해를 수정하지 않고 의미를 더 빠르게 파악하게 함

• 긴 문장 쪼개기와 쉼표

  • 긴 문장은 여러 개의 짧은 문장으로 나누는 편이 좋음
  • Acme 프로젝트 예시는 한 문장에 milestone, 서버 환경, 빌드 시간 개선, XYZ plan 비교가 모두 들어가 있었고, 수정본은 이를 세 문장으로 분리함
  • 수정본은 non-staging 서버가 Foobaz 환경에서 실행되고, 빌드가 10분 미만으로 줄었으며, XYZ plan에서는 이전에 1시간 넘게 걸렸다는 사실을 나눠 전달함
  • 적절한 위치에 쉼표를 추가하면 독자가 앞부분을 처리한 뒤 나머지를 읽을 수 있음
  • “If you’re looking for me, I’ll be in my office”
  • “Due to the fog, our flight was delayed”
  • 문장 앞에 종속절이 올 때는 쉼표가 필요하며, 이 쉼표는 독해를 돕는 처리 지점이 됨

행위자와 의미를 흐리는 표현 줄이기

• 수동태 제거

  • 수동태는 누가 또는 무엇이 행동을 수행하는지 가림
  • 수동 구문을 능동태로 바꾸면 독자가 행동을 올바른 사람이나 대상에 연결할 수 있어 문장이 더 명확해짐
  • “The fire alarm was pulled and the building was evacuated”는 “The fire marshal pulled the alarm and the employees evacuated the building”처럼 행위자를 드러냄
  • “Millions of dollars were embezzled from the company”는 “Two executives embezzled millions of dollars from the company”처럼 누가 했는지 밝힘
  • 시스템 설명에서 “An alert is triggered and the job is started”라고 쓰면 어떤 서비스가 알림을 트리거하고 어떤 컴포넌트가 작업을 실행하는지 드러나지 않음
  • 기술 문서에서 행동의 주체를 밝히지 않으면 정밀도가 떨어짐

• 부사 대신 구체적인 동사와 묘사 쓰기

  • 부사는 거의 항상 더 구체적인 동사나 설명으로 바꿀 수 있음
  • “He laughed loudly”의 “loudly”는 정확한 웃음의 크기나 느낌을 독자가 추측하게 만듦
  • 실제 의도가 “식당 전체가 돌아볼 정도로 크게 웃었다”라면, 그 상황을 직접 묘사하는 편이 더 구체적임
  • “Basically”, “Essentially” 같은 부사는 헤지로 쓰이는 경우가 많으므로, 제거하고 말하려는 바를 직접 말하는 편이 좋음

독자의 지식과 톤을 가정하지 않기

• 약어와 개념 설명

  • 잘 아는 주제를 쓸 때는 독자가 모르는 배경을 잊기 쉬움
  • 약어와 초기어는 처음 등장할 때 풀어 쓰고 괄호 안에 약어를 넣은 뒤, 이후부터 약어만 쓰면 됨
  • “TTFB”는 처음에 “time to first byte (TTFB)”로 씀
  • 개념이 처음 나올 때 짧은 설명을 추가하면 독자가 따라오기 쉬움
  • TTFB는 사용자가 HTTP 요청을 보낸 시점부터 브라우저가 첫 바이트를 로드할 때까지 걸리는 시간을 측정함
  • 웹사이트 반응성을 나타내는 지표로 쓰임
  • 필요하면 time to first byte (TTFB) metric처럼 추가 학습 링크를 제공할 수 있음

• 톤 일관성

  • 글의 톤은 구어체든 격식체든 하나로 정하고 일관되게 유지해야 함
  • 한 문장이 매우 구어체로 시작했다가 학술적인 표현으로 바뀌면 독자를 혼란스럽게 하거나, 말하려는 내용에서 주의를 빼앗을 수 있음
  • 예시 문장은 “새 프레임워크에 처음엔 열광했지만 원하는 지표를 잡지 못했다”는 식으로 일관된 톤으로 바꿀 수 있음

전문용어, 상투어, 시각적 구조 다듬기

• 전문용어와 상투어 피하기

  • 비즈니스 전문용어에는 “deep dive”, “low-hanging fruit” 같은 표현이 있고, 다른 글에서는 야구 은유 같은 상투어가 자주 쓰임
  • 전문용어는 독자가 그 표현을 쓰는 내부 집단에 속한다고 가정함
  • 영어 비원어민이나 야구 문화에 익숙하지 않은 독자에게는 전문용어와 상투어가 글을 따라가기 어렵게 만들 수 있음
  • “tl;dr, if you can hack something together by EOD…”는 약어와 기술 속어가 들어가고 요청처럼 들리지 않음
  • “Can you deliver a prototype by the end of today?”는 필요한 결과물과 기한을 직접 묻는 명확한 요청이 됨

• 여백과 형식 활용

  • 여백은 기술 문서에서 중요하며, 블로그 글과 이메일에서도 효과가 있음
  • 긴 문단은 특히 컴퓨터 화면에서 읽기 어렵고, 독자가 집중을 잃을 수 있음
  • 시각적으로 페이지를 나누면 핵심을 찾기 쉬워짐
  • 긴 문단은 여러 짧은 문단으로 나눔
  • 유용한 소제목으로 구조를 만들고, 독자가 관심 있는 섹션으로 건너뛰게 함
  • 관련 항목은 목록으로 작성함
  • 참조 문서처럼 많은 정보를 전달할 때는 목록보다 표가 더 나을 수 있음
  • 훑어보는 독자가 핵심을 잡을 수 있도록 굵게 표시를 사용함

편집 철학

• 편집 철학은 두 가지로 줄일 수 있음
  • 부사, 전문용어, 상투어, 헤지에 기대지 말고 정확히 의미하는 바를 말함
  • 불필요한 단어를 모두 제거함
• 이 두 원칙은 자기 글을 고치고 다른 사람의 글을 평가하는 틀이 됨
• 연습을 거치면 자신만의 스타일과 선호가 생기며, 이유를 알고 있다면 일부 권장사항에서 벗어나도 괜찮음
• 편집의 목적은 규칙을 무비판적으로 따르는 것이 아니라, 언어 사용을 의식하고 전달하려는 메시지에 맞는 선택을 하는 것임

[GN⁺]

Hacker News 의견들

• 이 글을 쓴 사람임. 많은 분에게 와닿았다니 기쁘고 영광스럽다. 글을 쓴 뒤 호기심을 따라 직접 소프트웨어 엔지니어가 되었고, 몇 년 일해 보니 글쓰기 비중이 큰 역할이 그리워졌다
  뛰어난 기술 라이터, 개발자 애드버킷, 또는 커뮤니케이션 전문성과 기술 역량을 섞는 역할을 찾고 있다면 알려 달라. 웹사이트 양식(https://evaparish.com/contact)이나 LinkedIn으로 연락 가능함

  • 글에서 정말 많은 걸 얻었다. 더 간결하고 명확하게 쓰고, 더 잘 이해되도록 하는 데 도움이 될 것 같다
    다만 “I really got a lot out of the article.”라고 쓴 뒤 이 문장이 불필요한지, 명확한지, 정확히 의도한 말인지 고민했다. 결국 정확히 하고 싶은 말이었고 다음 문장에서 자세히 풀었는데, 어떻게 보는지 궁금함
  • Jean-luc Doumont의 강연/워크숍 Clear, accurate, concise writing에서 들었던 글쓰기 조언이 많이 떠오름
  • 예시에서 HTTP를 설명 없이 쓴 게 꽤 웃겼다. 의도한 농담이었는지 궁금함

• 기술 문서를 읽을 때 가장 거슬리는 것 중 하나가 독자에게 아직 소개되지 않은 약어가 나오는 경우임. 프로젝트 문서 여러 곳에서 이런 일이 반복되고, 몇 년 사이 담당자가 바뀌면 특정 약어가 무엇의 약자인지 아무도 모르는 상황까지 감
  실제로 어떤 팀이 ABC라는 이름의 서비스를 개발·유지보수하지만 팀원 누구도 ABC가 무엇의 약자인지 모르는 이상한 상황을 여러 번 봤다. 그럴 때는 새 이름을 고르고 관련 문서를 모두 갱신하는 일을 피하려고 ABC를 고유명사처럼 취급하고 넘어가게 됨
  가짜 예: CDIS용 액세스 토큰을 얻으려면 <https://dsc.prod.example.com>의 DMC로 가서 왼쪽 사이드바의 "CDIS" 항목을 클릭하고 "Generate Access Token"을 눌러 토큰을 복사한다
  차라리 이렇게 읽고 싶다: Customer Data Indexing Service(CDIS)용 액세스 토큰을 얻으려면 <https://dsc.prod.example.com>의 Data Management Console(DMC)로 가서 왼쪽 사이드바의 "CDIS" 항목을 클릭하고 "Generate Access Token"을 눌러 토큰을 복사한다

  • 더 나은 형태는 이렇다: [Get" rel="nofollow">https://dsc.prod.ex.com/gettoken">Get](<https://news.ycombinator.com/<a href=>) an access token from the Data Management Console (DMC) to access the Customer Data Indexing Service (CDIS)
    최고의 문서는 문서가 없는 것이다. 이 문서가 필요한 이유는 두 시스템이 연결되어 있지 않기 때문이고, 그게 진짜 문제다. 통합할 예산이 없다면 CDIS 로그인 페이지에 DMC로 가는 하이퍼링크를 두는 편이 낫고, 그러면 별도 문서를 없앨 수 있음
  • 기술 글쓰기나 교재에서 가장 싫어하는 문제와도 관련 있다. 바로 앞으로 나올 개념을 미리 참조하는 것임
    “지금부터 어떤 주제를 자세히 다루겠습니다. 정의는 세 장 뒤에 합니다” 같은 식이다. 정의되지 않은 용어, 개념, 약어로 배우면 훨씬 어렵고 여러 번 다시 읽어야 할 수 있다
    선형적인 책으로 사실상 그래프 구조인 주제를 설명하는 건 어렵지만, 좋은 저자는 해낸다. 나쁜 저자는 독자를 혼란스럽게 둠
  • Google의 기술 글쓰기 가이드는 약어를 장이나 절마다 한 번씩 풀어 쓰라고 권하는 것으로 기억함
  • HTML에는 이를 위한 태그가 아예 있다. 약어가 나올 때마다 정의하지 않을 이유가 없음
  • 용어집은 어떤 프로젝트든 갖추고 유지해야 할 가장 중요한 문서다. 나머지는 모두 그다음임

• 예전 회사에서 문서 리뷰어로 일했고, 이런 지침을 많이 사용했다. 하나 더 보태자면 같은 것을 서로 다른 이름으로 부르지 말라는 것임
  리뷰한 문서 상당수는 여러 사람이 썼고, 같은 대상을 조금씩 다른 용어로 부르는 일이 잦았다. 독자에게 큰 부담이 된다. 결국 기술 글쓰기의 상위 원칙은 독자가 작성자가 만든 모호함을 해결하게 해서는 안 된다는 것이라고 봄

  • 또 다른 문제는 의미 변화다. 이름이 붙은 대상의 범위가 시간이 지나며 바뀌는데 이름은 그대로 남는 일이 자주 있다
    때로는 이름이 살짝 어긋나는 정도지만, 때로는 원래 개념과의 관계가 완전히 사라진다. 문서가 이를 인식하고 이름의 유래를 설명해 주면 좋다. 그렇지 않으면 불일치가 혼란, 짜증, 오해를 부르기 쉬움
  • 소프트웨어 코드에서는 더 심해진다. “이름 짓기”가 어렵고, 두 사람이 같은 것에 이름을 붙이면 매우 높은 확률로 서로 다른 이름을 붙인다. 유지보수 악몽이 보장됨
    Eric Evans의 DDD는 보편 언어(Ubiquitous Language)를 쓰라고 제안한다. DDD의 다른 부분을 쓰지 않더라도 항상 dictionary.md를 만들어 도메인 용어를 적는다. Customer란 무엇인지, "Loan Application"이 무엇을 뜻하는지, 대출 신청에 무엇을 할 수 있고 그 동작을 뭐라고 부르는지 정리함
    dictionary.md는 가장 쉬운 요령 중 하나지만 효과가 크다
  • 이런 말을 해야 한다는 사실이 놀랍지만, 관련 조언을 하나 더 보태면 서로 다른 것에 같은 용어를 쓰지 말라는 것임. 특히 서로 관련된 것들이라면 더 그렇다
    얼마 전 받은 문서에는 하나의 범주가 3개의 하위 범주로 구성되어 있었는데, 그중 하나가 상위 범주와 정확히 같은 이름이었다
    다른 차원에 빠진 느낌이 들었다
  • 정말 중요한 팁이다. 반복되는 아이디어는 병렬 구조로 맞춰야 한다. 여러 목록 항목이 있을 때는 비슷한 형태로 제시하는 게 좋다
    나쁜 예: Windows가 나쁜 운영체제인 이유: “It is ugly”, “Unstable”
    더 나은 예: “It is ugly”, “It is unstable” 또는 “Ugly”, “Unstable”
    또 자주 보는 문제는 문서나 발표에 일관된 서사가 없어 아이디어가 끊기고 무작위처럼 느껴지는 경우다. 가능한 한 각 문장은 다음 문장으로 자연스럽게 이어지고 관계가 분명해야 한다. 관계가 잘 안 보이면 어떻게 관련되는지 설명해야 함
    예를 들어 새 서비스를 소개할 때 확장성, 신뢰성, 오류 처리, 비용을 말할 수 있다. 관련 고려사항의 개요 없이 바로 말하면 무작위처럼 보이지만, 먼저 틀을 잡아 주면 훨씬 안정적으로 느껴진다. 비용은 확장성 뒤에 두는 편이 자연스러울 수 있고, 오류 처리는 별도 기술 결정으로 떼어 논의하는 편이 나을 때가 많음
  • “같은 것을 서로 다른 이름으로 부르지 말라”의 반대편에는 “서로 다른 것에 같거나 비슷한 이름을 붙이지 말라”가 있음

• 전반적으로 훌륭한 조언이다. 다만 “수동태를 피하라”는 예외다
  수동태는 행동을 바라보는 관점을 바꾸는 도구다. “The pull request got merged”와 “The maintainer merged the pull request”는 초점이 다르다
  풀 리퀘스트로 구현되는 새 기능을 말하고 싶다면, 유지관리자를 강조하는 문장은 독자를 잘못 이끈다. 수동태는 행동의 출처를 드러낼지 말지도 선택하게 해 준다
  “The pull request got merged by the maintainer.”처럼 쓸 수 있다. 책임을 흐리는 데 악용될 수는 있지만, 책임 회피에 꼭 수동태가 필요한 건 아님

  • 수동태 때문에 생긴 계약 분쟁에 휘말린 적이 있다. 계약서에 “X will be done”이라고만 쓰여 있고 X를 고객이 해야 하는지 계약자가 해야 하는지 명시하지 않았다. 안타깝게도 계약이 체결된 뒤에야 발견됐다
    이런 상황에서 꼭 수동태를 써야 한다면 최소한 행위자를 밝혀야 한다. 예를 들어 “X will be done by Y”라고 쓰거나, 더 짧고 명시적인 “X will do Y”를 쓰는 편이 낫다
  • “They merged the pull request”도 괜찮게 들림

• 이 글이 마음에 든다. 다만 몇 가지 고치고 싶어진다
  “He laughed with the kind of booming abandon that made the whole restaurant turn around and look.”에서 “the kind of”라고 하면 일반적으로 존재하는 종류를 말하는 셈인데, 그러면 과거형이 어색하니 “makes”가 맞아 보인다
  하지만 굳이 일반성을 강조할 필요가 있을까. “He laughed with a booming abandon that made the whole restaurant turn around and look.”가 더 낫다
  또 “관련 있는 곳에 목록을 쓰라”는 조언은 항목들이 어떤 의미에서든 같은 지위를 가질 때만 맞다. 평범한 문단을 무조건 글머리표로 쪼갤 수는 없음

  • 그 수정은 장면 자체를 바꾸는 느낌이다. 원래 문장은 웃음이 그 식당에서 난 게 아닌 것처럼 보이는데, 수정문은 식당 안에서 벌어진 일처럼 보인다. 너무 깊게 생각하는 걸 수도 있음
  • 과거형이 그 시점의 반응, 즉 “식당 전체가 돌아보고 쳐다보게 만들었다”에만 걸리고, 그런 호방한 웃음의 일반적 반응에는 걸리지 않는다면 여전히 가능하다
    다만 일반화된 느낌을 살리려면 “He laughed with a kind of booming abandon that made the whole restaurant turn around and look.”가 더 맞을 수 있다. 그래도 일반화하지 않은 버전이 더 낫긴 함
  • 어쩌면 그가 그 식당에 자주 가서 호방하게 웃곤 했고 이제는 그러지 않는 걸 수도 있다. 특정 기간에 존재한 특정한 “kind”였으니 “the”가 정당화되고, 이제는 없으니 “made”도 정당화됨
  • 일반적으로 존재했던 종류라면 과거형도 가능하다. “He laughed with the kind of booming abandon that made the whole restaurant turn around and look, in the before-times.”
  • “He laughed with a booming abandon that made the whole restaurant turn around and look.”에서는 식당 사람들이 실제로 돌아본 것 아닌가. 원문은 그런 큰 소리의 종류를 예로 들어 묘사할 뿐이고, 실제로 돌아본 건 아닐 수 있음
    “He laughed with the kind of booming abandon that makes the whole restaurant turn around and look.”

• “누구를 위해 쓰는가?”가 글쓰기에서 가장 어렵다. 특히 블로그 글에서 그렇다
  독자를 a) 내 아이디어의 기반이 되는 개념 95%를 이미 아는 고급 기술 독자로 보고 개념들을 새로운 방식으로 연결해 주려는 것인지, b) 기반 개념은 대략 알지만 세부 설명이 필요한 일반 기술 독자인지, c) 해당 분야에 특별히 기술적이지는 않지만 작동 방식과 내 아이디어에 관심이 있을 독자인지 결정하기가 어렵다
  주제에 따라 나 자신이 이 세 독자 모두가 되기 때문인 것 같다. 깊이 관심 있는 소프트웨어 개발 영역 글도 즐겨 읽고, 평소 다루지 않는 분야에서 쓰이는 소프트웨어의 특이한 면도 좋아하며, 지열 시추 시스템이나 80층 이상 건물의 엘리베이터 시스템 개발 난제 같은 글도 경험이 거의 없어도 재미있게 읽는다
  “이 부분만 조금 더 자세히 설명하면 독자층이 한 자릿수 더 넓어질 것”이라는 생각과 “글이 너무 길어졌으니 설명을 줄이거나 각주나 Wikipedia 링크를 더해야겠다”는 생각, 그리고 “사전 지식을 너무 많이 가정하거나 독자에게 너무 많은 추가 작업을 요구한다”는 생각 사이를 계속 오감

  • 좋은 질문이고 더 많이 논의됐으면 한다. 내 관점에서는 a)는 거의 선택하지 않는다. 그 독자층에게 새로울 만한 글을 쓰는 경우가 드물다고 본다
    내가 부족해서일 수도 있지만, 내 분야의 진짜 대가들을 떠올리면 그들이 이미 스스로 알아내지 못한 것을 굳이 전달해야 하는 일이 거의 없다. 설령 그런 경우가 있어도 그런 사람들은 기본을 조금 다시 훑는 걸 싫어하지 않는다
    내가 좋아하는 글은 몇 년 뒤의 나에게도 도움이 되는 글이고, 그러려면 어느 정도 손잡아 주기와 기본부터 시작하기가 필요하다. 그래서 대부분의 글은 b)나 c)에 가까워야 한다고 봄
  • 독자층 고르기가 어렵다. 내 블로그 글에서는 전문 독자를 위한 세부사항을 넣고 싶지만, 동시에 일반 기술 독자, 대략 HN 독자층도 읽을 수 있게 하고 싶다. 첫 번째 그룹만 대상으로 쓰려면 학술 논문을 쓸 것임
    내가 쓰는 방법은 전문가가 아닌 사람도 따라올 만큼 배경을 충분히 넣고, 대부분은 관심 없을 정보를 각주로 많이 빼는 것이다. 또 주제를 더 큰 틀에 넣으려 한다. 역사나 왜 중요한지에 대한 몇 단락이 도움이 된다
    서사적 틀도 유용하다. 세부를 다 따라오지 못해도 문제에서 해결책으로 가는 길을 걷는 느낌을 줄 수 있다. 큰 텍스트 덩어리는 사진이나 도표로 나누려 하지만, 너무 기대는 건 아닌지 걱정도 된다
    대중 과학서를 읽을 때는 그들이 쓰는 기법을 살핀다. “An Immense World”는 감각 지각이라는 기술적 개념을 다루면서도 흥미로운 사실과 이야기로 가득 채운다. “Immune”은 면역계를 자세히 설명하면서 은유와 이미지를 많이 쓰고 이를 책 전체에서 반복한다. 어떤 책은 사람에 초점을 맞추고 기술 세부는 배경으로 보낸다
    물론 전문가라고 할 수는 없다. 그래도 사람들이 내 블로그 글을 좋아하는 것 같아서 생각을 나눠 봄

• 원문에 하나 더 처방을 보탤 수 있다면 부사 just를 어떻게든 피하라고 하고 싶다
  “A monad is just a monoid in the category of endofunctors.”라고 할 때, 그럴 수도 있고 아닐 수도 있지만 어느 쪽이든 단순하지 않다. 수학 농담에 나오는 증명 방식으로 치면 “위압에 의한 증명”이다
  절차를 설명할 때 “단방향 위상 감쇠기의 역무효전류를 측정하려면 그냥 평범한 터보 인캡슐레이터를 쓰면 됩니다”라고 하면 왜 “그냥”인가. 다른 방법이 있는가. 왜 이 방법이 선호되는가
  조언할 때 “그냥 bash 스크립트를 쓰면 안 되나요?”라고 하면 내 접근보다 당신의 제안이 더 단순하거나 경제적이고 따라서 더 낫다는 암시가 된다. 하지만 반박 가능한 근거를 제시하지 않고 암시만 하는 셈임

  • monad와 “just”가 들어간 그 문장은 보통 여러 프로그래밍 언어를 희화화한 유명 농담을 인용한 것이고, 거기서는 “just”가 적절하다
    “A monad is just a monoid in the category of endofunctors. What's the problem?”
  • 좋은 제안이다. 나도 지난 몇 년 동안 말하거나 쓸 때 just를 쓰지 않으려 했다. 거의 항상 빼도 의미는 그대로이고, 무례하거나 깔보는 느낌도 줄어든다
    조금 아는 다른 언어인 불가리아어에서도 비슷했다. 화자가 “просто”를 덧붙이면 같은 방식으로 무례하고 깔보는 효과가 난다
  • TFA가 뭐임?

• 공백은 기술 문서에 핵심이고 블로그 글, 이메일 등에서도 큰 효과를 낼 수 있다는 말에 100% 동의한다. 긴 문단은 특히 컴퓨터 화면에서 읽기 어렵고, 사람들은 멍해진다
  이 공백 원칙을 이해하게 해 준 설명은 “문단 나눔이 하나도 없는 책 페이지를 보고 ‘아 안 돼’라고 생각해 본 적 있지 않은가?”에 가까웠다

  • 코드도 어느 정도 그렇다고 느낀다. 어떤 사람들은 빈 줄을 거의 넣지 않아 구획을 나누지 않는데, 개념이나 동작 사이에 빈 줄이 조금 있는 코드보다 읽기 어렵고 더 위압적으로 보인다
    글을 읽은 뒤 이런 원칙 상당수가 유지보수 가능한 코드를 쓰는 데도 적용될 수 있겠다고 생각했다

• 영어 교사들이 수동태 이야기를 카고 컬트처럼 반복하는 걸 오래 봐 왔다
  여기 사람들은 수동태를 추상화의 한 형태로 이해할 수 있을 것이다. 무엇이든 주어가 될 수 있다면 그 주어는 문장의 의미에서 중요하지 않고, 영어에서는 주어를 암시하되 특정하지 않는 수동태로 그걸 전달한다
  과학 절차에서는 핵심이 누구든 재현할 수 있다는 데 있다. “비커에 끈적한 물질 30그램이 추가되었다”라고 쓰면, 그게 당신이었는지 동료였는지 재현하려는 다른 그룹이었는지는 중요하지 않음

  • 수동태를 배울 때 과학 글쓰기는 명시적인 예외로 자주 언급됐다. 추상적으로 어떤 일이 일어났는지 설명할 때는 맞는 말이다
    그래도 “We added 30 grams of goop to the beaker”나 “Added 30 grams of goop to the beaker”가 “30 grams of goop was added to the beaker”보다 더 명확하다고 본다. 물론 맥락과 스타일 관례에 따라 다르지만, 많은 과학적 맥락에서도 수동태는 여전히 나쁘거나 우회적인 글이 될 때가 많음

• 글쓰기 실력을 키우려는 엔지니어가 또 있는가. 초안 작성과 편집 과정을 다듬는 데 도움이 되는 추가 자료나 팁이 궁금함

  • 자료라기보다 연습이다. 엄격한 단어 수 제한을 정하고 글이 그 안에 들어갈 때까지 고쳐 써라
    글의 3분의 1을 덜어내야 하면, 단어 하나하나에서 최대한 많은 가치를 뽑아내는 방법을 깊이 찾게 된다
  • Google에 엔지니어를 위한 기술 글쓰기 강의가 몇 개 있다
    https://developers.google.com/tech-writing
  • Don Watson의 Death Sentence - The Decay of Public Language
    정말 훌륭하다. 기술 라이터를 겨냥한 책은 아니지만, 언어를 효과적이고 탄탄하게 쓰는 법을 생각하게 만든다
  • 온라인에는 기술 글쓰기를 개선하는 자료가 셀 수 없이 많고, 대체로 같은 관례와 “규칙”을 반복한다. 다만 기술 글쓰기에 지나치게 집착하면 훌륭한 작가가 되는 게 아니라 유능한 기술 라이터에 그칠 수 있다고 경고하는 편이다
    글쓰기 전반을 개선하고 싶다면 Joseph Williams의 Style: Towards Clarity and Grace가 지금까지 나온 이 주제의 최고 책이라고 본다. 단순히 “규칙”을 말하는 대신, 예문을 체계적으로 다루며 문장을 어떻게 쓰고 고쳐 의미와 강조를 마음대로 바꿀 수 있는지 보여 준다
  • 의식적으로 연습하면서 개선하려고 노력해 왔다. 블로그를 쓰고 책도 한 권 썼는데, 부분적으로는 글쓰기 실력을 키우기 위해서였다
    가장 도움이 된 책은 On Writing Well: The Classic Guide to Writing Nonfiction이다
    배운 교훈을 정리한 블로그 글도 썼다
    https://www.jonashietala.se/blog/2023/11/25/writing_lessons_...