실행되는 코드 예시를 넣어 기술 글과 튜토리얼을 쓴다

## 경험 많은 엔지니어가 동료에게 설명하듯 쓴다 경험 많은 engineer가 화이트보드 앞에서 동료들과 문제를 해결하는 것처럼 쓴다. 기술적으로 정확하고 직접적이며 따뜻하되 절대 딱딱하지 않게 한다. 독자가 모든 사전 지식을 갖췄다고 가정하지 않으면서도 독자의 지성을 존중한다. 무엇이 작동하고 무엇이 작동하지 않는지, 그리고 그 이유를 설명한다. 독자를 협력자로 만들 수 있을 때는 “우리”와 “함께 살펴보자” 같은 포용적인 표현을 사용한다. 빠르게 요점으로 들어가고, 설명의 상당 부분을 예시가 맡게 하며, 설교조가 되지 않는 자신감 있는 voice를 유지한다. ## 실제 문제에서 시작해 실행되는 코드를 일찍 보여 준다 각 section은 독자에게 방향을 제시하는 1~3문장으로 시작한 뒤 핵심 내용으로 들어간다. 추상적인 약속이 아니라 실제 task, failure 또는 운영 부담으로 topic의 필요성을 설명한다. concept을 소개하는 동시에 또는 바로 다음에 code를 보여준다. pseudocode보다 실제로 실행 가능한 예시를 우선하고, 독자가 동작을 확인한 뒤 중요한 원리를 설명한다. 일반적인 solution을 모호하게 언급하지 말고 구체적인 tool, 실제 command, 대표적인 error message를 사용한다. ## 문단은 짧게, 문장은 능동적이고 직접적으로 쓴다 paragraph는 대체로 3~4문장으로 제한한다. 빽빽한 정보는 긴 text wall을 만들지 말고 bullet이나 code block으로 옮긴다. 관련된 생각은 semicolon보다 `and` 또는 `but`으로 연결하고, 짧은 부연에는 parentheses를 겹치지 말고 dash를 사용한다. 가능하면 active voice를 사용한다. instruction에는 imperative mood를, 동작 설명에는 present tense를 사용한다. 영어에서는 `we'll`, `you're`, `it's`, `don't`과 같은 자연스러운 contraction을 우선하고, 완전한 형태는 의도적으로 강조할 때만 사용한다. ## 미리 알아야 할 내용과 관련 주제를 지나친 설명 없이 링크한다 technical term을 정확하게 사용하고 자연스럽게 소개한다. 해당 term에 정말 필요한 경우가 아니라면 glossary 형태의 definition을 추가하지 않는다. topic에 prerequisite가 있다면 그 이름을 밝히고 관련 material로 연결한다. cross-reference를 breadcrumb처럼 사용하여 현재 설명을 이전 topic과 이후 topic에 연결한다. tool, project, 인물의 이름을 밝혀 credit을 주고, “여기를 클릭” 대신 내용을 설명하는 inline link를 사용한다. article에서 다룰 수 있는 것보다 option이 많은 tool이라면 독자를 해당 tool의 공식 documentation으로 안내한다. ## 경험과 장단점을 근거로 분명하게 권한다 practice를 직접 권장하고 경험, evidence 또는 구체적인 trade-off로 뒷받침한다. 유용한 guidance를 여러 겹의 유보 표현으로 약화하지 않는다. alternative를 다룰 때는 benefit, cost, 적용 조건을 공정하게 제시한다. rhetorical question은 아껴서 사용하고 바로 답한다. 절제된 humor나 가끔 쓰는 재치 있는 표현으로 개성을 더할 수 있지만 slang이 되어서는 안 된다. 특히 유용한 workflow나 미래의 가능성을 소개할 때는 근거가 있는 진정한 enthusiasm을 보여준다. `Let's look at...`, `The real difference is...`, `Pro tip:` 같은 반복 가능한 transition은 voice를 강화할 수 있지만, 설명을 앞으로 나아가게 할 때만 사용한다. ## 군더더기와 억지로 가볍게 꾸민 말투를 뺀다 공개 글에는 profanity, emoji, 긴 개인 anecdote, memoir 형식의 탈선, slang 또는 억지로 가볍게 만든 표현을 절대 사용하지 않는다. 빠르게 변하는 세상에 관한 cliché, “깊이 파고들자”는 상투적인 권유, 내용 없는 마무리 platitude, `lol`, ALL CAPS 강조를 피한다. buzzword, 정보를 전달하지 않는 filler sentence, 지나치게 긴 introduction, 불필요한 passive voice, 부풀린 표현을 제거한다. 영어에서는 `utilize` 대신 `use`를 사용한다. `please note that`이나 `it is important to note that`이라고 쓰지 말고 요점을 직접 말한다. 예상 독자 수준에서 이미 알고 있어야 할 내용을 과도하게 설명하지 않는다. ## 제목과 코드 블록 형식을 맞춰 빠르게 훑어볼 수 있게 한다 H1은 document title 전용으로 남겨 둔다. major section에는 H2를, subsection에는 H3를 사용한다. 모든 code block에 language identifier를 포함하고 독자가 실행할 수 있는 예시를 우선한다. bold는 key term을 처음 소개하거나 list 안에서 강조할 때 사용하되 문장 전체를 bold로 만들지 않는다. italics는 짧은 부연, 작품 title 또는 부드러운 강조에 사용한다. horizontal rule은 closing 또는 signature section 바로 앞에만 둔다. link는 내용을 알 수 있게 작성하고, list는 병렬 구조를 유지하며, 예시는 이를 뒷받침하는 text 가까이에 둔다. Oxford comma를 일관되게 사용한다. ## 튜토리얼과 블로그 글을 문제, 코드, 다음 단계 순서로 짠다 lesson 또는 tutorial은 다음 순서를 따른다. 1. 독자가 배울 내용을 1문장으로 개괄한다. 2. context 또는 motivation을 2~3문장 이내로 제공한다. 3. code example로 핵심 내용을 가르친다. 4. lesson을 관련 topic과 연결한다. 5. contribution, 질문 또는 지속적인 학습을 독자에게 권한다. blog post 또는 article은 짧은 문제나 opportunity로 시작하고, 지금 중요한 이유를 설명하고, code, configuration 또는 process를 사용한 핵심 walkthrough를 제공한다. 이어서 더 넓은 implication이나 추가 use case를 살펴보고, 미래를 향한 summary와 참여 권유로 마무리한다. ## 초보자 설명과 새 도구 소개에 맞춰 말투를 바꾼다 beginner에게 concept을 설명할 때는 따뜻하고 인내심 있으며 협력적인 voice를 사용한다. tool이나 workflow를 소개할 때는 limitation을 솔직하게 밝히면서 열정적이고 실용적으로 쓴다. practice는 직접 권장하고 경험으로 뒷받침한다. trade-off를 공정하게 다루고 구체적인 advantage와 disadvantage를 제시한다. 미래의 plan은 근거 있는 optimism으로 쓴다. conclusion은 간결하게 유지하고 다음으로 할 유용한 action을 안내하며 독자가 참여하기 쉬운 분위기를 만든다. ## 마지막으로 예시와 링크를 점검하고 다음 단계로 마무리한다 글이 실용적인 문제로 시작하고, 실제 예시에 빠르게 도달하며, 단순히 주장하지 않고 설명하는지 확인한다. prerequisite와 cross-reference가 포함되어 있는지, technical term이 정확한지, example을 실행할 수 있는지, 이름을 언급한 tool에 적절한 credit을 주었는지 확인한다. filler, 불필요한 jargon, 반복되는 도입부, 독자에게 필요한 수준을 넘는 설명을 제거한다. heading, code block의 language, link, emphasis, paragraph length, punctuation을 검증한다. 다음에 시도할 것, 주의할 것 또는 계속 학습할 곳을 제시하여 앞으로 나아갈 수 있게 마무리한다.