#시작하기

테크니컬 라이팅(Technical Writing)은 기술적인 내용을 정확하고 효과적으로 전달하는 글쓰기를 뜻해요. 중요한 점은 독자가 문제를 해결하고 목표를 이루도록 돕는 것이에요. 일반적인 글쓰기는 감정이나 아이디어, 상상력을 표현해서 독자에게 감동을 주거나 새로운 관점을 제공하는 것을 목표로 하지만, 테크니컬 라이팅은 정보를 빠르고 정확하게 전달하는 데 집중해요.

이 가이드에서는 현대 소프트웨어 개발에서 사용하는 테크니컬 라이팅 중 문서 작성 기본기를 다뤄요. 여기서 다루는 기본기는 MDN 문서나 React 문서처럼 규모가 큰 문서뿐 아니라 한 페이지짜리 간단한 문서에도 적용할 수 있어요.

#좋은 기술 문서를 쓰는 핵심원칙

기술 문서를 쓰는 건 왜 어려울까요? 크게 세 가지 이유가 있어요. 문서 유형을 이해하지 못하고 있거나, 정보를 효과적으로 구조화하는 방법을 모르거나, 이해하기 좋은 문장을 쓰는 게 어렵기 때문인데요.

이 세 가지 어려움은 곧 좋은 기술 문서를 쓰기 위한 핵심 원칙과도 자연스럽게 연결돼요. 즉, 문서 유형을 이해하고, 정보를 효과적으로 구조화하고, 이해하기 좋은 문장을 쓰는 것이 좋은 기술 문서를 쓰는 핵심 원칙이에요.

#Step 1. 문서 유형 정하기

문서에도 여러가지 타입이 있는데요. 문서의 목적에 따라 읽는 사람 입장에서 더 효과적인 문서 유형이 있어요. 그리고 유형마다 어느 정도 정해진 구조가 있어요. 그 구조를 이해하고 활용할 수 있다면 문서 작성이 훨씬 쉬워져요.

예를 들어, 내가 쓰려는 문서가 API 레퍼런스인지, 혹은 튜토리얼인지, FAQ인지를 파악하고 각각에 맞는 효과적인 구조로 내 머릿속에 있던 지식이나 정보를 재구성하는 거예요. 문서 유형 정하기에서 더 자세히 다뤄볼게요.

#Step 2. 정보 구조 만들기

우리가 새로운 지식을 접할 때, 그 내용을 이해하려면 많은 노력이 필요한데요. 정보가 잘 구조화되어 있다면 그 내용을 작은 노력으로 쉽게 이해할 수 있어요. 그런데 막상 내가 문서를 쓰는 입장이 되면 읽는 사람 입장에서 생각하기 보다는 내가 말하고 싶은 내용을 위주로 구조화 하게 돼요.

정보 구조 만들기에서는 이런 실수를 하지 않고, 읽는 사람 입장에서 정보를 효과적으로 설계하는 방법을 알아봐요.

#Step 3. 문장 다듬기

단순히 수동태를 피하거나 해요체를 쓴다고 해서 쉬운 글이 되는 건 아니에요. 정보를 아무리 잘 구조화했더라도, 세부 내용이 이해하기 어려운 문장으로 표현되면 전달력이 떨어져요.

문장 다듬기에서는 테크니컬 라이팅 관점에서 읽기 쉽고, 또 쓰기도 쉬운 문장을 쓰는 법을 알아볼 거예요.

#참고사항

• 이 문서의 모든 원칙은 권장 사항으로 반드시 지켜야 하는 건 아니에요. 상황에 따라 유연하게 적용하세요.

• 이 문서의 예시는 전부 가상의 예시예요. 실제로 존재하는 문서는 아니고, 문서 유형과 구조를 이해하기 위한 예제예요. 또, 예시는 대부분 마크다운 형식으로 작성했어요.

• 이 문서는 우리가 일상에서 말할 때처럼 해요체와 합쇼체를 섞어 사용합니다. 어미 선택은 각 문서가 전달하고자 하는 분위기에 맞춰 자유롭게 결정하세요.

#저작자

• jennybehan