개발자를 위한 글쓰기를 읽고 나서 이것저것 시도해보다가 쓰는 글.
–
스펙을 정리하고 전달하는 방법
스펙을 누군가에게 설명하는 방법은 여러가지가 있다.
- 문장
- 리스트
- 순서가 있는 리스트
- 도표
- 플로우챠트
생각나는 방법은 대략 이 정도이다. 우리(내 회사)는 일반적으로 슬랙에서 소통하면서 1번, 2번, 3번을 사용한다. 하지만 제품 개발하는 상황에서는 4번, 5번이 훨씬 효율적인 경우가 있다. 그런데도 문장, 리스트만을 사용한다.
왜? 개인적인 생각
- 슬랙이 그것밖에 제공을 안 해서 슬랙 밖을 나갈 생각을 잘 안 함. 노션이나 다른 툴은 켜기 귀찮으니까…!
- 문서화를 지양하는 문화. 그 자체가 모든 소통을 줄글로 해야할 것 같은 느낌
하지만, 그림을 이용할 필요가 있음을 요즘 절실히 느끼는 중.
그럴 듯한 사례로 예시를 들어보자
예시1) 앱에서 ‘일 시작하기’ 버튼을 누르면 어떻게 될까?
문장 사용 시
일 시작하기 버튼을 누르면 API를 호출합니다. API 내부에서는 먼저 일 시작할 수 있는 상황인지, 최대 근로 시간을 넘었는지 등을 먼저 검증을 한 뒤에 API를 호출한 시간을 시작 시간으로 하여 Task 라는 작업을 의미하는 Entity를 생성하여 DB에 저장합니다. 그런데! 일 시작 시 이미 같은 시간에 겹치는 작업이 있거나 이후 시간에 작업이 있다면 … (생략)
분기가 들어가는 순간 혼란의 도가니가 된다. 리스트와 순서가 있는 리스트도 마찬가지임. 하나의 스레드로 생각해야함.
순서가 있는 리스트 사용 시
그나마 꼼수로 분기를 표현할 수 있지만, 이런 느낌,,,?
-
- 일 시작 API 호출
-
- 일 시작 가능한 시간인지 검증함
-
- 최대근로 시간을 넘었는지 검증함
- 4-1) !!인 경우, @@함
- 4-2)인 경우, ^^함
- 4-3) &&인 경우, ((함
굳이?? 흐음… 문장과 똑같이 구리다.
플로우챠트를 쓰면 깔끔하다.
- 난 Excalidraw로 갈겨쓰는 걸 즐긴다. 귀엽기 때문임.
- Mermaid를 쓰면 공유하기 편해진다. 코드 기반으로 깔끔하면서 유지보수하기 쉬운 그림을 그릴 수 있다.
플로우챠트 사용 시
예시를 쥐어짜려니 좀 구리지만,, 대충 이런 느낌으로 그려짐. 굿~
예시2) 앱에서 ‘일 시작하기’ 버튼이 ‘일 다시 시작하기’로 바뀌어 보이는 조건은 뭘까?
리스트 사용 시
간단하게는 이렇게 복붙복붙 쓰기도하고,
- 출근 안 한 상태 → 버튼 라벨 ‘일 시작하기’로 표시
- 일이 진행중인 상태 → 버튼 라벨 ‘일 그만하기’로 표시
- 휴식이 진행중인 상태 → 버튼 라벨 ‘일 시작하기’로 표시
- 퇴근 상태 → 버튼 라벨 ‘일 다시 시작하기’로 표시
- 퇴근 상태가 아니지만, 출근한 상태 → 버튼 라벨 ‘일 시작하기’로 표시
중복 내용을 엮어서 쓰기도 함.
- 버튼 라벨 ‘일 시작하기’로 표시
- 출근 안 한 상태
- 일이 진행중인 상태
- 휴식이 진행중인 상태
- 버튼 라벨 ‘일 다시 시작하기’로 표시
- 퇴근 상태
하지만 한 차원이 더 늘어난다면? 으악!
도표 사용 시
도표로 해결 완료
| 버튼 라벨 (결과) | 출퇴 & 진행중인 작업 상태 | 비고 |
|---|---|---|
| 일 그만하기 | 일이 진행중인 상태 | |
| 일 다시 시작하기 | 퇴근 상태 | |
| 일 시작하기 | 출근 안 한 상태 | 기본값(default) |
| 휴식이 진행중인 상태 | ||
| 퇴근 상태가 아니지만, 출근한 상태 |
마크다운이라 셀 합치기는 못 했다. 하지만 ‘일 시작하기’에 중복된 ‘출퇴 & 진행중인 작업 상태’와 ‘비고’를 확장할 수 있는 형태로 표현 보기도 더 편함 (개비스콘 짤)
어렵지 않아요. ChatGPT와 함께라면…
개인적으로 Mermaid를 잘 익혀보고 싶은데, ChatGPT가 뭐든지 너무 잘 그려줘서 GPT와 함께하느라 아직 혼자서는 Mermaid 작성할 수 없는 애기 단계에 머물러있다.
아래는 예시1의 Mermaid 코드를 작성해준 대화이다. 완벽하게 호환되진 않고, 일부 syntax에 맞지 않는 이름을 수정해줘야한다. 대표적으로 코드에 들어간 ( 요런 문자가 들어가면 mermaid.live 에 넣어도 화를 내니 그 정도는 손으로 수정해줌…
우리 GPT 똑똑해. 코드를 그냥 넘겨도 찰떡같이 잘 짜준다. ChatGPT는 쥐도새도 모르게 상상력으로 다른 코드를 끼워넣기에, 암살 당할 수 있으니 확인은 나의 몫이다. 눈으로 잘 살펴봐 주자.
음? 이건 약간 실망…
여튼 이렇게 GPT로 잘 뽑히고 있다.
개비스콘 짤 한번 더
끝