이슈 트래커와 사내 위키

Chapter 4. 개발 권한 받기

"티켓? 위키? 또 뭔가를 해야 하는 건가?"

소스 저장소 권한도 받았다. 개발 서버도 접속했다. DB도 연결했다. 이제 정말 개발할 수 있을 것 같은데, 팀장님이 슬랙으로 또 메시지를 보낸다.

"Jira 계정 생성하셨나요? 위키에서 온보딩 문서부터 읽어보세요."

'Jira? 위키? 그게... 뭐지?'

검색창을 연다. "Jira란" 수십 개의 블로그가 뜬다. 이슈 추적 도구, 프로젝트 관리, 애자일, 스프린트... 단어는 들어봤는데 실제로 어떻게 쓰는 건지 모르겠다.

슬랙을 보니 다른 개발자들이 "PROJ-1234 티켓 확인했습니다", "위키에 정리해놨어요" 같은 대화를 하고 있다. 다들 당연하다는 듯 쓰고 있는데, 나만 모르는 것 같다.

'티켓이 뭐야? 번호는 왜 저렇게 붙어있지? 위키는 또 어디 있는 거야? 온보딩 문서는 뭐지?'

걱정하지 마라. 이슈 트래커와 사내 위키는 생각보다 간단하다. 여기서는 각 도구가 무엇인지부터, 계정 생성,

프로젝트 접근, 티켓 읽는 법, 위키 활용법까지 차근차근 알아보자.

이슈 트래커가 뭘까?

이슈 트래커(Issue Tracker)는 "해야 할 일을 관리하는 도구"다. 쉽게 말하면 디지털 포스트잇이다. 이러한 도구가 왜 필요한 알아보자.

업무 기록

누가, 언제, 무엇을 해야 하는지

진행 상태는 어떤지

완료됐는지 확인

커뮤니케이션

기획자가 개발자에게 요구사항 전달

QA가 버그 리포트 작성

팀원들끼리 진행 상황 공유

히스토리 추적

왜 이 기능을 만들었는지

누가 결정했는지

과거 논의 내용 확인

에피소드

나도 처음엔 이해가 안 됐다. "메일로 하면 되는 거 아니야? 슬랙으로 말하면 되잖아?" 그런데 일주일 지나니까 알겠되었다. 슬랙 메시지는 흘러가 버린다. 며칠 전 대화를 찾으려면 스크롤을 한없이 올려야 한다. 메일은 더 심하다. 답장이 꼬리에 꼬리를 물면 어디가 최종 결정인지 알 수가 없다.

그런데 이슈 트래커는 다르다. 티켓 하나에 모든 대화가 담긴다. 2달 전 논의도 클릭 한 번이면 다 보인다. "아, 그래서 이렇게 만든 거였구나" 히스토리가 다 남아 있다.

입사 2주차에 선배가 "저번에 이야기했던 그 기능, 어떻게 하기로 했더라?"라고 물어봤다. 나는 슬랙을 뒤지기 시작했다. 10분을 찾았는데 못 찾았다. 선배가 웃으면서 "티켓 번호 알아?" 하고 PROJ-456을 열어줬다. 거기 모든 대화가 다 있었다. 기획 의도, 디자인 시안, 기술 검토, 최종 결정까지. 그때 깨달았다. 이게 왜 필요한지.

주요 이슈 트래커 도구

회사마다 사용하는 도구가 다르다. 하지만 사용빈도가 높은 도구는 보통 크게 세 가지로 나뉜다.

Jira (지라)

가장 보편적으로 사용하는 트래커 도구다. 개인적으로 디자인이 별로지만 기능적으로는 가장 강력하다.

주로 사용하는 회사

중견기업, 대기업

글로벌 기업

애자일 방법론 사용하는 조직

특징

Atlassian 제품 (Confluence와 연동)

가장 많이 쓰임

강력한 기능, 하지만 복잡함

커스터마이징 자유로움

스프린트, 에픽, 스토리 등 애자일 용어 사용

YouTrack (유트랙)

필자가 제일 좋아하는 트래커 도구이다. 깔끔한 디자인 편리한 직관적인 UI까지 마음에 쏙 든다. 새로운 트래커를 구축한다면 유트랙을 추천한다.

주로 사용하는 회사

스타트업, IT 기업

JetBrains 도구 쓰는 회사

특징

JetBrains 제품 (IntelliJ 만든 회사)

Jira보다 UI 세련됨

속도 빠름

키보드 단축키 강력

무료 버전도 기능 많음

Redmine (레드마인)

너무나 편리하지만 오래된 도구이다. 최근에는 팀에서 레드마인을 도입하려고 하자 MZ 개발자들이 이 오래된 도구에 대해 탐탁치 않아 했던 기억이 있다. 그래도 오랫동안 무료로 사용했던 마치 과거에 메신저를 제패했떤 버디버디가 떠오르는 트래커 도구이다.

주로 사용하는 회사

중소기업

오픈소스 프로젝트

예산 제약 있는 조직

특징

완전 무료 오픈소스

자체 서버에 설치

기능은 기본적

UI가 좀 구식

커스터마이징 자유로움

실전 팁

회사가 어떤 도구를 쓰는지는 팀장님이나 인사팀 안내 메일에 나와 있다. "Jira 계정을 생성해주세요" 또는 "YouTrack 초대 링크를 보냈습니다" 같은 식으로

이슈 트래커 계정 생성하기

대부분 트래커 도구의 가입은 이메일로 초대 링크가 온다. 이 링크를 통해 가입할 수 있다.

Jira 초대 메일

[회사명] Jira에 초대되었습니다 아래 링크를 클릭하여 계정을 활성화하세요.

https://company.atlassian.net/secure/signup...

YouTrack 초대 메일

YouTrack에 초대되었습니다 초대를 수락하려면 아래 링크를 클릭하세요.

https://company.youtrack.cloud/...

Redmine

계정이 생성되었습니다 아이디: jhlee 임시 비밀번호: Welcome123!

계정 생성 절차

1단계: 링크 클릭

초대 메일의 링크 클릭

브라우저에서 페이지가 열림

2단계: 정보 입력

이름 입력 (실명)

비밀번호 설정

회사 이메일 주소 확인

3단계: 이메일 인증

인증 메일이 다시 옴

"Verify Email" 클릭

4단계: 로그인

생성한 계정으로 로그인

프로필 사진 업로드 (선택)

실전 팁

프로필 사진은 메신저에 쓴 사진과 같은 걸로 하자. 동료들이 "아, 이 사람이구나" 바로 알아볼 수 있다.

프로젝트 접근 권한 받기

계정을 만들었다고 모든 프로젝트를 볼 수 있는 건 아니다. 프로젝트별로 권한이 필요하다.

자동 추가되는 경우

팀장님이 미리 프로젝트에 추가해둠

로그인하면 바로 프로젝트 목록이 보임

별도 신청 불필요

수동 신청하는 경우

프로젝트 관리자에게 요청

팀장님께 "OO 프로젝트 권한 부탁드립니다" 슬랙 보내기

보통 당일 처리

접근 가능한 프로젝트 확인

Jira

좌측 상단 "프로젝트" 드롭다운 클릭

내가 속한 프로젝트 목록 보임

YouTrack

좌측 사이드바에 프로젝트 목록

별표 표시로 즐겨찾기 설정 가능

Redmine

상단 메뉴 "프로젝트" 클릭

접근 가능한 프로젝트 리스트

티켓(이슈) 읽는 법

티켓이 뭔가요?

"해야 할 일 하나"를 티켓이라고 부른다. 포스트잇 한 장이라고 생각하면 된다.

티켓 번호

PROJ-1234 형식

PROJ는 프로젝트 약자

1234는 고유 번호

자동으로 증가

각 회사마다. 고유한 티켓 번호를 사용한다. 가장 보편적인 방식은 프로젝트 약자와 숫자의 조합이다. 특별히 고민하지 않아도 회사에서 사용하는 네이밍에 맞게 사용하면 된다.

에피소드

첫 주에 선배가 "PROJ-523 한번 봐봐" 라고 했을 때, 나는 523이 뭔지 몰라서 멍하니 있었다. 선배가 웃으면서 Jira 링크를 보내줬다. 클릭하니 티켓 상세 페이지가 열렸다. "아, 이게 티켓 번호구나." 그때부터 개발자들이 숫자로 대화하는 이유를 알았다. "로그인 버그 있어요"보다 "PROJ-523 보세요"가 훨씬 정확하다. 티켓 번호만 말하면 모든 컨텍스트가 공유되니까.

티켓 상태 업데이트하기

티켓은 읽기만 하지 않는다. 상태를 바꿔줘야 한다. 이 것들이 언제 바꿔어야 할지 알아보자.

작업 시작할 때

To Do -> In Progress로 변경

담당자를 본인으로 설정

코드 리뷰 올릴 때

In Progress -> In Review로 변경

리뷰 승인받으면

In Review -> Done으로 변경

에피소드

신입사원 시절 내가 실수한 일이 있다. 티켓을 받아서 열심히 작업했다. 코드도 짰고, 로컬에서 테스트도 했다. 그런데 티켓 상태를 To Do 그대로 놔뒀다. 오후 4시쯤 팀장님이 슬랙으로 "개발님, PROJ-678 아직 시작 안 하신 거예요?" 하셨다. 당황해서 "아니요! 거의 다 했어요!" 했더니 "그럼 상태를 In Progress로 바꿔주세요" 하셨다. 그때 배웠다. 티켓 상태는 내 작업 현황을 팀에 알리는 신호등이구나.

사내 위키가 뭘까?

사내 위키(Wiki)는 "회사의 모든 지식이 모여 있는 곳"이다. 회사 버전 위키백과라고 생각하면 된다.

지식 공유

개발 가이드

코딩 컨벤션

API 문서

트러블슈팅 히스토리

온보딩

신입 개발자 가이드

서비스 소개

팀 소개

자주 묻는 질문(FAQ)

문서화

회의록

프로젝트 명세서

기술 스펙

배포 절차

에피소드

입사 3주차쯤, 빌드 에러가 계속 났다. 한 시간을 헤맸다. 포기하고 선배한테 물어보려는데, 문득 "위키에 있지 않을까?" 생각이 들었다. Confluence에서 "빌드 에러"를 검색했다. 정확히 같은 에러를 겪었던 시니어가 작성한 문서가 나왔다. 원인, 해결 방법, 재발 방지까지. 5분 만에 해결됐다. 그때 깨달았다. 위키는 회사의 집단 기억이구나.

주요 사내 위키 도구

Confluence (컨플루언스)

jira를 만든 회사라 그런지 디자인은 무뚝뚝하다. 그래도 역시 기능은 강력하다. 많은 회사에서 사용중이다.

주로 사용하는 회사

Jira 쓰는 회사

중견기업, 대기업

특징

Atlassian 제품 (Jira와 연동)

가장 많이 쓰임

페이지 구조 체계적

템플릿 다양

강력한 검색 기능

Notion (노션)

메모앱이지만 충분한 위키 역할을 해낸다. 개인적으로 너무 아기자기 해서 기록된 노트들에게 눈이 안간다.

주로 사용하는 회사

스타트업, IT 기업

젊은 조직

특징

UI 예쁘고 직관적

블록 단위 편집

데이터베이스 기능 강력

무료 플랜도 기능 많음

속도 빠름

GitLab Wiki / GitHub Wiki

깃헙, 깃랩을 쓰면 자동적으로 wiki도 사용이 가능하다. 추가요금이 붙는 것도 아니다. 그런데 이 좋은걸 필자가 다녔던 회사에서는 제대로 사용한걸 본적이 없다. 기록이 코드와 같은 주소상에 있어서 여러모러 편리하다.

주로 사용하는 회사

개발팀만 쓰는 위키

소규모 팀

특징

코드 저장소와 함께 관리

마크다운으로 작성

Git으로 버전 관리

간단하고 가벼움

실전 팁

회사가 어떤 위키를 쓰는지는 온보딩 메일에 대부분 나와 있다. "Confluence 계정을 생성했습니다" 또는 "Notion 워크스페이스에 초대했습니다" 같은 식으로 그리고 여러 위키를 혼합해서 사용하는 경우가 있다. 이런 경우에는 위키마다 사용 용도가 다르거나 위키를 중간에 교체했을 확률이 높다. 어디 위키를 먼저 읽고 써야 하는지 물어보자.

위키 접근 권한 받기

자 이제 위키를 읽어보고 싶다면 권한을 받아야 한다. 권한을 받는 방법을 알아보자.

자동 초대되는 경우

입사하면 인사팀이 자동으로 워크스페이스에 추가

회사 이메일로 초대 링크 받음

링크 클릭하면 바로 접근 가능

수동 신청하는 경우

팀장님이나 전산팀에 요청

"Confluence 접근 권한 부탁드립니다" 슬랙 보내기

보통 당일 처리

초대 수락하기

Confluence

초대 메일 링크 클릭

Atlassian 계정으로 로그인 (Jira와 동일 계정)

워크스페이스 목록에 회사 추가됨

Notion

초대 메일 링크 클릭

Notion 계정 생성 또는 로그인

좌측 사이드바에 회사 워크스페이스 추가됨

GitHub Wiki

저장소 접근 권한 있으면 자동으로 위키도 접근 가능

별도 초대 불필요

온보딩 문서부터 읽기 시작

온보딩 문서란

"신입 개발자가 제일 먼저 읽어야 할 문서"다. 회사 생활의 교과서라고 생각하면 된다. 2번 3번 정독으로 읽어보자

온보딩 문서에 뭐가 있을까?

회사 소개

회사 비전, 미션

주요 서비스 소개

조직도

개발팀 소개

팀 구조

각 팀이 담당하는 서비스

팀원 소개

개발 환경 구축

필수 프로그램 설치 리스트

저장소 클론 방법

로컬 개발 환경 세팅

코딩 컨벤션

네이밍 규칙

코드 스타일

커밋 메시지 규칙

배포 프로세스

배포 담당자

배포 시간대

배포 절차

FAQ

자주 묻는 질문들

누구에게 뭘 물어봐야 하는지

위키에 문서 작성하기

신입은 처음엔 읽기만 하면 된다. 하지만 몇 주 지나면 직접 문서를 쓸 일이 생긴다. 그렇다면 언제 문서를 쓰는지 알아보자.

트러블슈팅 기록할 때

어려운 버그 해결했을 때

다음에 또 겪을 수 있는 문제

해결 방법 공유

새 기능 명세서를 정의 할 때

내가 만든 기능 설명

API 엔드포인트 추가

사용 방법 안내

온보딩 문서 업데이트 할 때

"이 부분이 불명확했어요"

최신 정보로 수정

에피소드

처음으로 위키에 문서를 썼던 기억이 난다. Docker 컨테이너가 계속 죽는 문제를 3시간 동안 삽질하다가 해결했다. 선배가 "이거 위키에 정리해둬. 너 같은 신입이 또 겪을 수 있어" 하셨다. 떨리는 마음으로 Confluence 페이지를 만들었다. 제목은 "Docker 컨테이너 재시작 반복 문제 해결". 문제 상황, 원인, 해결 방법을 차근차근 적었다. 발행 버튼을 누르는데 손이 떨렸다. '이거 다른 사람이 보면 어떻게 생각하려나...' 다음 날 시니어가 슬랙으로 "문서 잘 봤어요. 덕분에 빠르게 해결했습니다 " 메시지를 보냈다. 그때 느꼈다. 내가 회사에 기여할 수 있구나. 그러므로 거침없이 기록하자.

이슈 트래커와 위키, 이제 알겠다.

Jira 계정을 만들었다. 프로젝트에 접근했다. 티켓 목록이 쭉 펼쳐진다.

PROJ-1145: 회원가입 API 개선 PROJ-1146: 로그인 에러 처리 PROJ-1147: 비밀번호 찾기 페이지

'와... 진짜 실제 업무 티켓들이다.'

하나를 클릭해본다. 상세한 설명이 나온다. 댓글도 달려 있다. 기획자, 디자이너, 개발자들이 대화한 흔적이 보인다.

'이렇게 일이 진행되는구나...'

슬랙에 팀장님이 메시지를 보낸다.

"온보딩 문서 읽어보셨나요? 궁금한 거 있으면 언제든 물어보세요."

답장을 한다.

"네, 지금 읽고 있습니다! 정말 자세하게 정리되어 있네요. 감사합니다!"

팀장님이 답장한다.

"좋아요! 다음 주부터 본격적으로 업무 시작할 건데, 천천히 적응하시면 돼요."

미소가 지어진다.

Jira 화면을 내려다본다. 티켓 목록이 쭉 나열되어 있다. 아직 내게 할당된 티켓은 없지만, 곧 생길 것이다.

Confluence 탭을 연다. 온보딩 문서가 열려 있다. 아직 다 읽지 못했지만, 천천히 읽으면 된다.

'드디어... 회사 생활의 도구들을 다 갖췄다.'

VPN, 메일, 메신저, 소스 저장소, 개발 서버, DB, 이슈 트래커, 위키.

모든 계정이 만들어졌다. 모든 권한을 받았다.

이젠 비공개로 되어 있던 회사의 기록들까지 볼 수 있게 되었다.