SA문서와 readme 작성

SA와 README 작성 과정 및 주의사항

 

프로젝트를 체계적으로 관리하고 성공적으로 공유하기 위해 **SA(System Architecture)**와 README.md 문서를 작성하는 것이 중요하다.

---

1. SA 문서

SA(System Architecture) 문서는 프로젝트의 전반적인 설계와 방향성을 제시하는 문서
팀원들이 프로젝트 구조를 명확히 이해하고 개발 및 유지보수 과정에서 참고할 수 있는 가이드가 됨

 

1-1. SA 문서의 주요 내용

• 프로젝트 개요: 프로젝트의 목적과 주요 기능, 동작 방식
• 구성 요소: 프로젝트를 구성하는 주요 컴포넌트와 역할
• 기술 스택: 사용된 기술, 프레임워크, 도구, 그리고 선택 이유
• 요구사항 충족 여부: 설계가 프로젝트의 요구사항을 어떻게 충족하는지
• 다이어그램: 서비스 구조, 데이터 흐름, 시스템 구성 요소 등을 시각화

1-2. SA 문서의 중요성

SA 문서는 단순히 초반에 작성하고 끝내는 문서가 아님
개발이 진행됨에 따라 최신화를 반복해야 함
최신화된 SA 문서는 팀원 간 의사소통을 원활하게 하고 프로젝트 구조를 개선할 수 있는 기회를 제공함
특히, 개발 완료 후에는 트러블슈팅 내용을 추가해 유지보수에도 활용 가능함

 

1-3. 와이어프레임

와이어프레임은 프로젝트의 사용자 인터페이스(UI) 설계를 시각적으로 표현하는 도구

와이어프레임 작성 시 유용한 사이트

• Lucidchart: 직관적인 인터페이스로 와이어프레임 설계 가능
• Figma: UX/UI 디자인 도구로 와이어프레임 설계와 팀 협업에 적합
• Draw.io: 무료로 사용할 수 있는 간단한 와이어프레임 도구
• Miro: 화이트보드 기반으로 실시간 협업과 설계 가능

1-4. 다이어그램 

프로젝트의 전반적인 흐름, 데이터 처리 과정, 시스템 구조를 한눈에 보여줌

다이어그램 작성 시 활용 도구

• Lucidchart: 흐름도와 데이터 설계도를 쉽게 작성 가능
• Draw.io: 무료로 사용할 수 있는 데이터 흐름도 작성 도구
• Canva: 시각적으로 깔끔한 다이어그램 제작에 유용
• Visio: 마이크로소프트의 전문 설계 도구

---

2. README 문서

README.md는 프로젝트를 처음 보는 사람들에게 프로젝트를 설명하는 문서
특히 GitHub와 같은 플랫폼에서 프로젝트의 첫인상을 결정하는 역할

 

2-1. README 문서의 주요 내용

• 프로젝트 소개: 프로젝트의 목적과 주요 기능 설명
• 설치 방법: 프로젝트를 어떻게 설치하고 실행할 수 있는지
• 사용법: 주요 기능과 사용 예시, 간단한 시연 영상
• 기여 방법: 프로젝트에서 본인의 기여 항목
• 트러블 슈팅: 문제 해결 과정과 기술적 의사결정 기록

2-2. README 작성의 중요성

README는 프로젝트를 알지 못하는 사람들에게 프로젝트의 가치를 전달하는 브로셔 같은 문서
취업용 포트폴리오에서는 면접관이 가장 먼저 확인하는 문서이기 때문에 자신이 무엇을 기여했는지 명확히 보여야 함
README에 문제 해결 과정과 기술적 고민의 흔적을 담으면, 추가 질문을 유도할 수 있음

---

3. 작성 과정 요약 및 주의사항

1. SA 작성 과정
   • 프로젝트 초반에 작성하고, 개발 중에도 최신화 필요
   • 다이어그램과 와이어프레임을 적극 활용해 시각적 가독성을 높임
   • 트러블슈팅 기록은 개발 후기에 추가
2. README 작성 과정
   • 설치 및 실행 방법, 주요 기능 설명을 코드 블록과 함께 작성
   • 본인의 기여 항목을 구체적으로 기록
   • 트러블슈팅 과정을 상세히 설명
3. 주의사항
   • SA와 README는 각각의 목적과 대상을 염두에 두고 작성
   • SA는 개발팀의 이해를 돕는 설계 문서, README는 외부인을 위한 브로셔로 구분
   • 두 문서는 서로 보완적인 관계임

---

SA와 README 문서 작성은 단순히 프로젝트를 정리하는 것이 아니라, 프로젝트의 품질과 가치를 높이는 과정