토스, 테크니컬 라이팅 가이드 공개
(technical-writing.dev)좋은 기술 문서를 쓰는 핵심 원칙
1. 문서 유형 정하기
문서의 목적에 따라 더 효과적으로 글을 쓰는 방법이 다름
- 학습 중심 문서: 새로운 기술이나 도구를 처음 접했을 때, 흐름을 파악하는 목적
- 문제 해결 문서: 배경 지식이 있을 때 특정한 문제를 해결하는 목적
- 참조 문서: 이미 사용 방법을 알지만, 특정 기능이나 API 사용법을 확인하는 목적
- 설명 문서: 개념, 원리, 배경 지식을 자세히 이해하는 목적
2. 정보 구조 만들기
새로운 지식을 이해하려면 노력이 필요하지만, 정보를 구조화하면 노력을 덜 들일 수 있음
- 한 페이지에서 하나만 다루기
- 가치를 먼저 제공하기
- 효과적인 제목 쓰기
- 개요 빠뜨리지 않기
- 예측 가능하게 하기
3. 문장 다듬기
문장의 전달력을 높이면 독자가 내용을 더 쉽게 이해할 수 있음. 세부 내용이 이해하기 어려운 문장으로 표현되면 전달력이 많이 떨어짐
- 문장의 주체를 분명하게 하기
- 필요한 정보만 남기기
- 구체적으로 쓰기
- 자연스러운 한국어 표현 쓰기
- 일관되게 쓰기