핸드북 튜토리얼 목표 #

핸드북은 무엇인가에 대해 알아본다.
핸드북으로 문서를 작성할 수 있게 된다.
핸드북에 PR¹로 문서 작업을 할수 있게 된다.
github web editor의 기본을 배운다.

핸드북 #

핸드북은 무엇인가? #

로캘리 핸드북은 로캘리에서 기술적이지 않은 부분까지 포함한 어떤 일을 시작하기 위한 시작점이 되는 것을 목표로 한다.

신규 입사자의 온보딩부터 사내 커뮤니케이션 방법, 회사의 비젼과 가치, 실무 개발 툴 설정, 빌드 그리고 배포 등 모든 것을 핸드북에 기술 한다. 팀원 누구나 작성과 의견 제시를 할 수 있으며 적극적으로 권장한다.

본 핸드북에 영감을 준 Gitlab’s Handbook처럼 많은 부분을 투명하게 외부로 공개하는 것을 목표로 하고 있으나 현재는 극히 일부만 공개하고 있다.

핸드북의 장점 #

읽는 것은 듣는 것 보다 빠르다.
읽는 것은 비동기로 가능하고 다른 팀원을 방해하거나 기다리지 않아도 된다.
우리가 일하는 방식을 공개함으로써 이를 읽어본 인재 영입을 쉽게 한다.
온보딩에 관한 모든 내용을 기록하므로써 온보딩을 쉽게 한다.
다른 팀이 무엇을 하고 어떻게 일하고 있는지를 보고 이해할 수 있어서 협력을 쉽게 한다.
핸드북 변경점(git changeset)을 쉽게 알수 있어서 논의가 쉽다.
핸드북에 변경 내역을 올리는 것으로 누구나 쉽게 회사 프로세스 변경에 기여할 수 있다.

위키 또는 컨플루언스, 노션을 쓰지 않는 이유 #

느리다. 문서 한 두개 만들때는 아주 빠르다. 하지만 문서가 길어지거나 이미지가 많아지거나 메뉴가 많아지면 급격히 느려지기 시작한다. 반면에 본 핸드북 방식은 vscode 같은 에디터로 작업할 수 있기 때문에 web ui로 고통받을 일이 없다.
문서 변경점 관리가 안된다. 변경 내역을 볼수 있기는 하지만 유연하게 할 수가 없다. 그래서 충돌 처리가 어렵다.
문서가 내 컴퓨터에 없다. 네트워크 문제가 있거나 서비스가 종료될 걱정을 할 필요가 없다.

핸드북으로 작성 할 내용 #

회사 매뉴얼
업무 매뉴얼, 플레이북
회의록, 업무 일지
지라로 커버되지 않는 모든 프로젝트 문서

핸드북 문서 작성하기 #

핸드북 변경 2가지 가이드 #

간단한 수정 #

다음의 몇 가지 예외 사항에 대해서는 간단히 지금 처럼 수정해도 된다. 단, 반드시 commit message에 종류를 명시해야 한다.

문법이나 오타 수정
공백 수정
문서 내용 백업 혹은 이동
개인 페이지 로그

간단한 수정 페이지

일반적인 수정 #

간단한 수정에 해당하는 예외를 제외하고는 다음의 절차를 따른다.

web ide 부르고 branch 생성하기
1. 페이지 하단에 있는 “웹IDE로 페이지 수정"을 눌러 github web ide를 부른다.
2. 하단의 “main” branch² 표시를 선택한 후 “Create New Branch"를 누른다.
3. 연결된 jira ticket이 있으면 다음의 규칙에 따라 branch 이름을 선택해 생성한다.
  1. jira ticket이 있는 경우
    {지라티켓}-{짧은내용} 예) ENG-50-add-build-script
  2. jira ticketr이 없는 경우
    {짧은내용} 예) eng-add-build-script
4. 녹색의 Switch to Branch를 눌러서 해당 브랜치로 변경한다.
5. 원래 수정하고자 했던 파일을 찾아 간다. (이 부분은 github web ide가 나중에 자동으로 원본 파일로 가도록 픽스 할 것 같음)
핸드북 내용 수정, 삭제, 추가
1. 원하는 위치에 right click으로 New File, New Directory, Upload...을 선택해서 내용을 수정한다.
commit 하기
1. ctrl+shift+G를 누른다. 혹은 왼쪽 sidebar 위에서 세번째 를 눌러서 source control tab으로 간다.
2. ‘Changes’에 있는 변경 사항을 확인한다.
  1. 잘못 된 내용이 있다면 ctrl+shift+E를 누르거나 왼쪽 sidebar 맨 위의 를 눌러서 원하는 파일을 재 수정한다.
3. ‘Changes’에 마우스를 올리면 나오는 아이콘을 눌러서 원하는 변경 내역을 선택한다. 개별 파일을 선택해서 원하는 파일만 를 눌러서 commit할 수도 있다.
4. ‘commit message’를 입력한다.
  {내용} 예1) ENG-50: 빌드 스크립트 추가 예2) 빌드 스크립트 추가
5. 상단의 ‘SOURCE CONTROL’ 우측의 아이콘을 눌러서 최종 commit 한다.
PR 만들기
1. 상단의 ‘SOURCE CONTROL’ 우측의 아이콘을 누른다.
2. Create 버튼을 눌러서 PR을 만든다.
3. 🎉 축하합니다. 첫번째 PR을 만드셨습니다.
리뷰어 선택
1. 화면 오른쪽에 ‘Reviewer’에서 + 버튼을 누르고 원하는 사람을 선택하면 해당 멤버에게 리뷰 알림이 간다.
최종 병합
1. 핸드북 PR에서 만든 PR을 찾아서 선택한다.
2. 리뷰가 끝났으면 ‘Merge pull request’를 눌러서 main에 병합한다.
3. 🎉 축하합니다. 첫번째 좋은 방법으로 핸드북에 기여하셨습니다.