Markdown업무레포

마크다운은 가벼운 마크업 언어로서 간단한 문법으로 문서를 만들어낼수 있다. 회사에서는 주류로 쓰이지는 않지만 보고용 문서를 제외하고 간단하게 업무 및 개발내용을 적는 기술문서나 간단한 메모등에 매우 편리하다.

  • Gitlab
  • Mermaidjs

Gitlab 을 사용하여 업무레포 공유

회사에서 일부 프로그램 배포를 위해 Gitlab이 도입되어 있는데 이때 업무용으로 레포를 부탁하여 생성했다.

이 레포는 Markdown 문서가 대부분이고 때론 Txt파일 또는 업무외 별도 개발 소스를 관리한다.

Git브랜치

몇명 되지는 않지만 여러사람이 한 레포를 공유한다. 하지만 이는 단지 업무문서를 관리하는 것이므로 거창한 브랜치 전략이 필요없다.

  1. 개발자 별로 브랜치를 따고, 개별 브랜치에 작성 및 커밋, 푸시한다.
  2. Gitlab에서 “Merge Requests"를 작성하여 본인이 병합

다만 Main브랜치는 push금지로 보호한다.

--- title: 업무용 레포 간단 브랜치 --- gitGraph commit id: "start" branch developer1 branch developer2 checkout developer1 commit commit checkout developer2 commit checkout main merge developer1 id: "MR1" merge developer2 id: "MR2"

gitignore 개발진행문서관리

회사에서는 단기/중기/장기 단위로 개발요청이 올라오며 개발자 혹은 PM의 역할로 참여하게 된다.

개발에 필요하거나 진행하면서 발생한 이슈,적용포인트 등 모든것을 적으며 배포ID 등까지도 관리. 이는 기존 회사에서 보고용으로 쓰는 잘-정형화된 문서 스타일은 아니며. 자유롭게 상황에 따라 맞춰 메모용으로 작성한다.

gitignore 문서에 “진행중"인 폴더를 적고, 업무레포에는 “완료된” 폴더를 추가한다.

TXT
// gitignore
/진행중/*
  • “진행중"에 관리하던 메모문서가 개발이 완료되면 “완료된” 폴더로 옮겨서 커밋, 푸시, 병합
  • 추후 비슷한 개발건이 있을때 검색하여 같은 팀원(혹은 본인)이 작성했던 메모를 보고 힌트를 얻는다.

개발진행문서 템플릿

진행문서는 포맷이 자유로워야 하지만 너무 자유롭다면 어떻게 작성해야할지 막막할 수 있다. 따라서 팀에 따라 알맞게 어느정도는 템플릿을 제공한다.

MD
# 개발요청
어떤 개발인지 간단한 설명

## 1. 일정
25.03.20 ~ 25.04.20 (오픈일)

## 2. 관련인
PM XXX, 개발자1 , 개발자2,  현업1, 현업2

## 3. 적용업무
매매업무 중 서버1 실시간 매매

### 3.1. 적용포인트
기존 ~ 적용되어 있었으나 ~로 인해  ~ 형태로 바꿈
코드예시 등등.. 

### 3.2. 소스관리
소스리스트 등 관리

## 4. 테스트 
1. 초기세팅방법
2. B업무개발자 배치수행 
3. 일부데이터 변경후 테스트
쿼리예시 등등

## 5. 배포
ID나 종류등을 관리 PM이면 각 개발자 것까지 관리

## 6. 참고
이슈사항 및 대화내용, 녹취, 트러블등 모든것을 적음.

위는 일종의 틀이며 중간내용은 원하는대로 마음대로 바꾸어도 된다.

  • 메일이나 쪽지, 통화 등의 문답 내용은 그 자체를 백업하는 것만으로도 당시 상황을 짐작할수 있다.
  • 특히 현업의 말바꾸기 등을 고려하여 항시 증거를 남길 것.

Mermaidjs 다이어그램

다이어그램을 간단하게 그릴수 있는 툴인데 Markdown과 결합하여 엄청나게 유용한 툴이 된다.

아래 2개의 다이어그램을 많이 활용하지만 그외에도 다양한 다이어그램을 지원한다.

Graph

Gitlab 버젼에 따라 다르지만 이전버젼인 경우 ‘flowchart’ 지원이 안되는 경우가 있다. 이때는 아주 유사한 ‘graph’ 를 사용한다.

  • DB와 연관된 그림을 그리기 좋다.
  • 배치Job 등을 그리기에 더 알맞다.
TXT
graph LR
FileA -.-> |Read| Batch1 --> | insert | Table1[(Table1)]
Batch1 --> | insert | Table2[(Table2)]
graph LR FileA -.-> |Read| Batch1 --> | insert | Table1[(Table1)] Batch1 --> | insert | Table2[(Table2)]

subgraph

어디에 속해 있다는 것을 표현하고 싶을때. 즉 어떤 서버안에서 어떤 프로세스가 동작한다를 표현하고 싶을떄 유용하다.

graph LR RelyServer subgraph Server1 service1 end Server1 -.- RelyServer

sequence Diagram

시퀀스 다이어그램이 정말정말로 아주 유용하다. 흐름을 나타낼때.

  • 외부기관과 회사와의 통신 흐름을 표현하기 유용
  • 현업을 한 객체로 두고 표현해도 좋음
  • 강조하고 싶은 부분을 좀더 세분화해도 됨
TXT
sequenceDiagram
autonumber
participant 현업
participant 서버
participant 외부기관

현업 ->> 서버 : 전송버튼
note over 서버 : DB에서 데이터를 읽어 파일생성
서버 ->> 외부기관 : 파일 Faxxxxx0001.dat 전송

외부기관 ->> 서버 : 정상응답 R000
sequenceDiagram autonumber participant 현업 participant 서버 participant 외부기관 현업 ->> 서버 : 전송버튼 note over 서버 : DB에서 데이터를 읽어 파일생성 서버 ->> 외부기관 : 파일 Faxxxxx0001.dat 전송 외부기관 ->> 서버 : 정상응답 R000

업무설명문서

업무진행문서는 추후 다시 업무를 진행할때 힌트는 되지만 단편적인 개발에 국한된다. 따라서 업무의 전반적인 부분을 파악하기 힘들다. 장기 개발요청시 한 업무부분에 대해 첫 세팅부터 종결까지 완전한 개발을 진행할때 업무의 시작부터 끝까지 어떤 플로우로 진행되는지 “업무설명문서"를 별개로 작성해도 좋을 것이다.

템플릿

회사마다 그리고 업무마다 성격이 다를텐데 업무 통째로 설명하기 위해서는 Time-Line 별로 설명하는게 좋을 것이다. 또 기술적인 부분과 비즈니스적인 2가지 부분으로 나누면 좋다. 이때 위에서 설명한 다이어그램을 적극적으로 활용하여 그림으로 설명한다. (이해가 쉽다)

TXT
# ~~업무
~~ 업무는 ~로 인해 도입되었다.  
문서버젼 1.0 ~~~작성  25.03.20

## 1. 인터페이스
~ 기술적으로 업무부분과 연결하는 부분 설명

### 1.1. ~~
~~ 를 이용하여 연결한다. 
### 1.2. 스펙문서
* 해석방법: '시트'는 ~를 나타낸다.
### 1.3. Config
연결을 위해 세팅해야하는 설정값 설명 예시.

## 2. 비즈니스

### 2.1. 03:00 시간대 변경 
새벽에 ~ 준비를 위해 시간대 변경작업한다. 

### 2.2. 07:00 실시간 ~ 시작선언
실시간으로 서비스 

다양한 다이어그램 및 코드로 서비스 설명

### 2.3. 21:00 마감 및 후처리 

다이어그램 및 코드로 설명

한계

  • 사람마다 생각이 다르다.
  • 각 개인 툴에 너무 적응하여 공동작업이 익숙하지 않을 수 있다.
  • 마크다운과 mermaid 라는 것을 새로 익혀야 한다.
  • 업무설명문서가 많아지면 변경시마다 찾아서 변경사항 업데이트 하는데 시간이 든다.

절충점 개발진행문서 까지는 공동작업으로 데이터를 모으는것이 좋다고 설득한다.