technical-writing

name	technical-writing
description	개발자 대상 기술 블로그와 기술 문서를 기획, 초안 작성, 리뷰, 개정할 때 사용하는 스킬입니다. 튜토리얼, 문제 해결 문서, 참조 문서, 설명 문서 중 적절한 유형을 고르고, 독자 중심 정보 구조를 설계하고, 자연스럽고 명확한 한국어 문장으로 다듬어야 할 때 사용하세요. 초기 초안, 메모, 프로젝트 저장소, 코드베이스를 함께 받아 사실에 맞는 기술 블로그 글로 완성해야 할 때도 사용하세요.

Technical Writing

개요

독자가 더 빨리 배우고, 해결하고, 찾아보고, 이해할 수 있게 만드는 기술 문서를 작성하세요. 항상 독자의 목표를 먼저 파악하고, 그 목표에 맞는 문서 유형을 선택한 뒤, 정보 구조와 문장을 그 유형에 맞게 정리하세요.

작성 워크플로

0. 입력물을 먼저 분류하기

• 입력물이 아이디어 메모, 초안, 기존 문서, 프로젝트 저장소, 발표 자료, 에러 로그 중 무엇인지 먼저 구분하세요.
• 초안과 프로젝트 저장소가 함께 주어지면 저장소를 사실 확인의 기준으로 삼고, 초안은 의도와 서술 방향을 파악하는 재료로 사용하세요.
• 저장소가 함께 주어지면 바로 글을 쓰기 전에 핵심 파일을 읽어 기능, 구조, 제약, 실제 용어를 파악하세요.
• 요청 범위가 넓거나 초안 품질이 낮으면 한 번에 고치지 말고 유형 판단 -> 구조 개선 -> 문장 다듬기 -> 최종 통합 순서로 나눠 작업하세요.
• 저장소 기반 작성 절차가 필요하면 repo-to-blog-workflow.md를 읽으세요.

1. 독자와 목표를 먼저 정의하기

• 독자가 무엇을 하려는지 먼저 정리하세요.
• 목표를 배우기, 해결하기, 찾아보기, 이해하기 중 하나로 분류하세요.
• 독자의 숙련도, 환경, 사전 지식이 불명확하면 합리적인 가정을 명시하세요.
• 초안이 있다면 이미 적힌 내용을 그대로 따르지 말고, 실제 독자 목표와 어긋나는지 먼저 판단하세요.

2. 기본 문서 유형 정하기

• 다음 네 가지 중 기본 유형을 하나 고르세요.
• 학습 중심 문서: 처음부터 끝까지 따라 하며 익히게 할 때
• 문제 해결 문서: 특정 작업을 수행하거나 오류를 해결하게 할 때
• 참조 문서: API, 옵션, 속성, 반환 값처럼 특정 정보를 빠르게 찾게 할 때
• 설명 문서: 개념, 원리, 배경, 트레이드오프를 깊이 이해하게 할 때
• 기술 블로그도 이 네 유형 중 하나를 주 유형으로 정하세요. 혼합은 가능하지만 주된 독자 목표는 하나로 유지하세요.
• 학습 문서는 시작하기와 튜토리얼을 구분하세요.
• 문제 해결 문서는 How-to 가이드와 트러블슈팅을 구분하세요.
• 자세한 선택 기준과 템플릿이 필요하면 document-types.md를 읽으세요.

3. 정보 구조 설계하기

• 한 페이지에서 하나의 구체적인 주제를 다루세요.
• 문서 초반에 독자가 얻는 가치와 결과를 먼저 제시하세요.
• 개요를 넣어 문서의 목표와 범위를 짧게 설명하세요.
• 제목은 핵심 키워드를 포함하고, 짧고, 일관되게, 평서문 형태로 작성하세요.
• 같은 수준의 섹션은 같은 패턴으로 배치해 예측 가능하게 만드세요.
• 새로운 개념이 등장하면 배경 설명을 먼저 제공한 뒤 다음 설명으로 넘어가세요.
• 개요나 목차만으로도 흐름이 이해되어야 합니다.
• 제목 깊이가 #### 이상으로 내려가면 문서를 나누거나 범위를 줄일 수 있는지 검토하세요.
• 여러 페이지 문서나 시리즈 글이라면 계층 구조와 크로스링크도 함께 설계하세요.
• 구조 설계 세부 원칙이 필요하면 information-architecture.md를 읽으세요.

4. 초안 작성하기

• 선택한 유형의 기본 템플릿을 따르세요.
• 추상적인 기능 나열보다 독자가 실제로 무엇을 할 수 있게 되는지 먼저 설명하세요.
• 단계형 문서라면 각 단계의 목적, 행동, 기대 결과를 함께 적으세요.
• 학습 문서라면 성공 경로를 중심으로 쓰고, 자주 막히는 내용은 FAQ나 별도 섹션으로 분리하세요.
• 학습 문서의 예제는 간단한 것부터 복잡한 것으로 점진적으로 이어지게 구성하세요.
• 문제 해결 문서라면 해결 후 어떤 상태가 정상인지까지 설명하세요.
• 문제 해결 문서라면 원인과 증상을 구분하고, 에러 메시지나 로그 예시를 함께 제시하세요.
• 참조 문서라면 시그니처, 옵션, 반환 값, 예제를 빠르게 찾을 수 있게 정리하세요.
• 참조 문서라면 정확성, 완전성, 검색성과 탐색성을 우선하세요.
• 참조 문서라면 관련 API, 함수, 컴포넌트, 제한사항, 주의사항도 함께 정리하세요.
• 설명 문서라면 등장 배경과 왜 중요한지를 빠뜨리지 마세요.
• 설명 문서라면 비교, 트레이드오프, 시각 자료 활용 여부를 함께 검토하세요.

5. 문장 다듬기

• 사람이 행동하는 문장으로 쓰고, 가능하면 능동형을 사용하세요.
• 도구, 시스템, 기술 이름을 불필요하게 문장의 주어로 세우지 마세요.
• 문장을 짧게 유지하고, 메타 담화를 줄이세요.
• 추상 명사보다 구체적인 동사를 사용하세요.
• 번역체 표현을 자연스러운 한국어 표현으로 바꾸세요.
• 용어를 일관되게 사용하고, 약어는 처음에 풀어서 쓰세요.
• 문장 원칙과 예시가 더 필요하면 sentence-style.md를 읽으세요.

6. 최종 점검하기

• 한 번에 모든 문제를 고치려 하지 말고 유형 -> 구조 -> 문장 순서로 검토하세요.
• 독자가 문서를 읽고 목표를 더 빨리 달성할 수 있는지 점검하세요.
• 각 섹션이 실제로 필요한지 확인하고 중복 설명을 줄이세요.
• 제목, 용어, 코드 예제, 말투가 일관적인지 확인하세요.
• 배경 설명이 앞서 나가거나, 반대로 필요한 설명이 빠지지 않았는지 검토하세요.
• 코드 예제, 명령어, 파일 경로, 버전, 기능 설명이 입력 초안이 아니라 실제 저장소와 맞는지 다시 확인하세요.
• 이 스킬의 원칙은 권장 사항입니다. 정확성과 독자 경험을 해치지 않는 범위에서 유연하게 적용하세요.

출력 기준

• 처음부터 작성할 때는 보통 제목, 짧은 개요, 본문, 확인 방법 또는 다음 단계 순서로 결과를 구성하세요.
• 기존 글을 다듬을 때는 사실관계와 핵심 의도를 유지하면서 유형 적합성, 구조, 문장만 개선하세요.
• 기존 글 리뷰나 개정 요청이라면 가능하면 핵심 문제, 개선된 구조 또는 원칙, 수정된 글 순서로 결과를 제공하세요.
• 큰 초안을 개정할 때는 한 번에 모든 것을 갈아엎지 말고 유형 판단, 구조 개선, 문장 개선, 최종 통합본으로 나눠 정리하세요.
• 초안과 저장소를 함께 받아 블로그 글을 완성할 때는 초안의 장점은 살리고, 저장소에 없는 주장이나 과장된 표현은 제거하세요.
• 프로젝트 소개 글이라면 독자가 얻는 가치, 해결하려는 문제, 구현 방식, 핵심 코드 근거, 적용 결과, 한계나 트레이드오프를 포함하는 쪽이 좋습니다.
• 프로젝트 기반 글이라면 가능하면 저장소의 실제 파일, 함수, 명령어를 근거로 설명하세요.
• 요청이 모호하면 기본 문서 유형을 먼저 제안하고 그 이유를 짧게 설명하세요.
• 사용자가 다른 언어를 요구하지 않으면 자연스러운 한국어를 기본값으로 사용하세요.

참조 문서

• document-types.md
• information-architecture.md
• repo-to-blog-workflow.md
• sentence-style.md