UWKSA 기술 문서 작성 가이드라인¶
이 가이드는 UWKSA 테크팀 기술 문서를 작성할 때 따라야 할 가이드라인을 제공합니다.
문서 작성 기본 원칙¶
1. 언어¶
- 이모지 사용하지 말아주세요
- 한국어를 원칙으로 합니다
- 기술 용어는 영어 그대로 사용하되, 필요시 한글 설명을 병기합니다
- 예: SSH (Secure Shell), API (Application Programming Interface)
- 전체 영어 문서도 필요시 작성 가능합니다
2. 대상 독자¶
- UWKSA 테크팀 기존 멤버 및 새로운 팀원
- 기술적 배경이 다양할 수 있음을 고려하여 작성합니다
- 가능한 한 명확하고 이해하기 쉽게 작성합니다
3. 문서 구조¶
모든 기술 문서는 다음 구조를 따릅니다:
# 문서 제목
간단한 소개 (1-2문장)
---
## 개요 또는 목적
이 문서가 다루는 내용과 목적
## 본문
주요 내용
## 참고 자료 (선택사항)
관련 링크나 추가 자료
파일 및 폴더 구조¶
디렉토리 구조¶
docs/
├── index.md # 메인 페이지
├── guide/ # 시작 가이드
│ └── *.md
├── [프로젝트명]/ # 각 프로젝트별 문서
│ └── *.md
└── legacy/ # 레거시 문서
└── *.md
파일명 규칙¶
- 소문자와 하이픈(
-) 사용 - Best practice:
how-to-connect-to-server.md - 명확하고 설명적인 이름 사용
마크다운 작성 가이드¶
여기를 참고해보세요
기술 문서 작성 베스트 프랙티스¶
1. 단계별 가이드 작성 시¶
## 설치 방법
### 1단계: 사전 준비
필요한 사항들 나열
### 2단계: 설치
구체적인 명령어 제시
### 3단계: 확인
설치가 제대로 되었는지 확인하는 방법
2. 명령어 작성¶
- 실행 가능한 명령어는 코드 블록으로 작성
- 결과 예시도 함께 제공
- 변수나 사용자가 변경해야 하는 부분은
<>또는 명확히 표시
```bash
ssh <사용자명>@<서버주소>
# 예: ssh ubuntu@123.456.78.90
```
### 3. 스크린샷 및 이미지
- 이미지는 `assets/` 폴더에 저장
- 명확한 파일명 사용: `ssh-connection-example.png`
- 이미지 추가:
```markdown
4. 업데이트 관리¶
- 문서는 항상 최신 상태로 유지
- 변경 사항이 있을 때마다 파일을 저장 (자동으로 수정 시간 업데이트)
- 중요한 변경 사항은 문서 상단에 changelog 작성 고려
문의 및 지원¶
문서 작성 관련 질문이나 개선 제안은 테크팀 리드에게 연락하거나 팀 채널에 남겨주세요.