읽기 어렵다면, 만들기도 어렵다
Source: Dev.to
Hello, I’m Maneshwar. I’m working on FreeDevTools online — a free, open‑source hub where developers can quickly find and use tools without the hassle of searching all over the internet.
1979년, 싱가포르의 총리 리콴유는 정부에서 명확하고 간단한 영어 사용의 중요성에 대해 이야기했습니다. 수십 년이 지난 지금, 그의 메시지는 오늘날 기술 및 소프트웨어 세계에도 완벽하게 적용됩니다.
The Problem with Communication in Tech
우리 산업은 복잡한 시스템—분산 서비스, 마이크로서비스, 머신러닝 파이프라인, 클라우드 인프라, 확장 아키텍처—을 구축합니다. 하지만 기술이 기하급수적으로 발전한 반면, 커뮤니케이션 품질은 그만큼 향상되지 못했습니다.
우리는 모두 이런 경우를 본 적이 있습니다:
- 아무도 이해하지 못하는 전문 용어로 가득 찬 PRD와 RFC
- 필요 이상으로 길어진 엔지니어링 이메일 및 Slack 스레드
- 실제로 필요한 정보를 제외하고 모든 것을 설명하는 문서
- 설명이 “fix”뿐이고 코드가 400줄이나 바뀌는 풀 리퀘스트
우리는 영리함을 지나치게 찬양하고, 명료함은 충분히 강조하지 못합니다.
Clarity moves teams. Complexity slows them down.
“Do not try to impress by using big words; impress by the clarity of your ideas.” — Lee Kuan Yew
“정부”를 “소프트웨어 엔지니어링”으로 바꿔도 여전히 사실입니다.
Write So Anyone Can Understand
디자인 문서, 온보딩 가이드, 혹은 커밋 메시지를 작성할 때:
- 독자는 상황에 대해 아무것도 모른다고 가정한다
- 가능한 가장 간단한 단어로 의미를 전달한다
- 형용사와 불필요한 채우기 표현을 제거한다
- 긴 문장은 나눠서 쓴다
- 모호한 표현보다 구체적인 진술을 선호한다
해독이 필요한 글을 썼다면 이미 실패한 것입니다.
좋은 테스트: 새로운 인턴이 한 번 읽고 핵심 아이디어를 이해할 수 있는가? 아니라면 다시 쓰세요.
Bad Writing Destroys Velocity
리 총리는 관료들이 쓴 혼란스러운 문장을 예로 들었습니다—문법적으로는 맞지만 논리적으로는 의미가 없는 문장. 우리는 기술 분야에서도 다음과 같은 문장으로 같은 실수를 합니다:
- “We should leverage strategic synergies across cross‑functional service layers.”
- “Optimizing system throughput with asynchronous parallelized concurrency guarantees.”
- “Needs architectural refactoring for scalable resilience.”
그게 도대체 무슨 뜻일까요?
더 나은 대안:
- “두 팀이 같은 서비스를 공유하면 작업을 중복하지 않아도 됩니다.”
- “작업을 병렬로 실행하면 시스템이 더 빨리 완료됩니다.”
- “트래픽이 증가해도 시스템이 다운되지 않도록 재설계합니다.”
아이디어가 강력하다면 장식이 필요 없습니다.
Writing = Thinking
명확하게 생각하지 않으면 명확하게 쓸 수 없습니다. 무언가를 간단히 설명하는 데 어려움을 겪는다면 아직 완전히 이해하지 못한 것입니다. 글쓰기는 명료함을 강요하고, 그래서 최고의 엔지니어가 훌륭한 문서를 만드는 이유이기도 합니다.
Make Feedback Normal
리 총리는 비서를 통해 자신의 글을 교정받았다고 합니다. 엔지니어링에서도 같은 문화가 필요합니다:
- 불명확한 PR 설명에 코멘트 달기(예: “이게 무슨 뜻인가요?”)
- 모호함을 지적하기
- 재작성 장려하기
트집을 잡기 위한 것이 아니라, 나중에 발생할 혼란을 방지하기 위함입니다. 열린 커뮤니케이션은 진행 속도를 높이고, 침묵은 이를 죽입니다.
Why This Matters for the Future of Software
기업이 성장함에 따라 커뮤니케이션이 실제 병목이 됩니다. 컴퓨팅 파워가 아니라 말이죠. 코드는 리팩터링할 수 있고, 인프라는 업그레이드할 수 있습니다. 서로를 이해하려고 시간을 낭비하는 것이 기술 분야에서 가장 비싼 비용입니다. 업계는 거대한 어휘보다 깨끗한 사고가 필요합니다—‘복잡성 숭배’보다 단순함이 필요합니다.
The Takeaway
다음과 같이 작성하세요:
- 모두가 이해할 수 있게
- 아이디어가 명확히 드러나게
- 모호함이 전혀 없게
- 목적이 분명히
왜냐하면 기술 분야도 정부와 마찬가지이기 때문입니다:
If we cannot communicate clearly, we cannot build anything great together.
👉 Check out: FreeDevTools
Any feedback or contributors are welcome! It’s online, open‑source, and ready for anyone to use.
⭐ Star it on GitHub: freedevtools