개발자를 위한 글쓰기를 읽고 나서 이것저것 시도해보다가 쓰는 글입니다.
–
스펙을 정리하고 전달하는 방법
스펙을 누군가에게 설명하는 방법은 여러 가지가 있습니다.
- 문장
- 리스트
- 순서가 있는 리스트
- 도표
- 플로우차트
대략 이 정도가 떠오릅니다. 저희 팀에서는 일반적으로 Slack에서 소통하면서 1번, 2번, 3번을 사용합니다. 하지만 제품 개발 상황에서는 4번, 5번이 훨씬 효율적인 경우가 있습니다. 그런데도 문장과 리스트만 사용하게 됩니다.
왜 그럴까요?
- Slack이 그것밖에 제공하지 않아서, Slack 밖을 나갈 생각을 잘 안 하게 됩니다. 노션이나 다른 도구는 켜기 귀찮으니까요.
- 문서화를 지양하는 문화 자체가 모든 소통을 줄글로 해야 할 것 같은 느낌을 줍니다.
하지만 그림을 활용해야 할 필요성을 요즘 절실히 느끼고 있습니다.
그럴 듯한 사례로 예시를 들어보겠습니다
예시1) 앱에서 ‘일 시작하기’ 버튼을 누르면 어떻게 될까?
문장 사용 시
일 시작하기 버튼을 누르면 API를 호출합니다. API 내부에서는 먼저 일 시작할 수 있는 상황인지, 최대 근로 시간을 넘었는지 등을 먼저 검증을 한 뒤에 API를 호출한 시간을 시작 시간으로 하여 Task 라는 작업을 의미하는 Entity를 생성하여 DB에 저장합니다. 그런데! 일 시작 시 이미 같은 시간에 겹치는 작업이 있거나 이후 시간에 작업이 있다면 … (생략)
분기가 들어가는 순간 혼란의 도가니가 됩니다. 리스트와 순서가 있는 리스트도 마찬가지입니다. 결국 하나의 스레드로만 생각해야 합니다.
순서가 있는 리스트 사용 시
그나마 꼼수로 분기를 표현할 수는 있지만, 이런 느낌입니다.
-
- 일 시작 API 호출
-
- 일 시작 가능한 시간인지 검증
-
- 최대근로 시간을 넘었는지 검증
- 4-1) !!인 경우, @@함
- 4-2)인 경우, ^^함
- 4-3) &&인 경우, ((함
문장과 마찬가지로 보기 좋지 않습니다.
플로우차트를 쓰면 깔끔합니다.
- Excalidraw로 빠르게 그리는 것을 선호합니다. 손그림 느낌이 귀엽기 때문입니다.
- Mermaid를 쓰면 공유하기 편해집니다. 코드 기반으로 깔끔하면서 유지보수하기 쉬운 그림을 그릴 수 있습니다.
플로우차트 사용 시
예시를 억지로 만들어서 다소 어색하지만, 대략 이런 형태로 그려집니다.
예시2) 앱에서 ‘일 시작하기’ 버튼이 ‘일 다시 시작하기’로 바뀌어 보이는 조건은?
리스트 사용 시
간단하게는 이렇게 나열할 수 있고,
- 출근 안 한 상태 → 버튼 라벨 ‘일 시작하기’로 표시
- 일이 진행중인 상태 → 버튼 라벨 ‘일 그만하기’로 표시
- 휴식이 진행중인 상태 → 버튼 라벨 ‘일 시작하기’로 표시
- 퇴근 상태 → 버튼 라벨 ‘일 다시 시작하기’로 표시
- 퇴근 상태가 아니지만, 출근한 상태 → 버튼 라벨 ‘일 시작하기’로 표시
중복 내용을 엮어서 쓸 수도 있습니다.
- 버튼 라벨 ‘일 시작하기’로 표시
- 출근 안 한 상태
- 일이 진행중인 상태
- 휴식이 진행중인 상태
- 버튼 라벨 ‘일 다시 시작하기’로 표시
- 퇴근 상태
하지만 한 차원이 더 늘어난다면 감당하기 어려워집니다.
도표 사용 시
도표로 깔끔하게 해결됩니다.
| 버튼 라벨 (결과) | 출퇴 & 진행중인 작업 상태 | 비고 |
|---|---|---|
| 일 그만하기 | 일이 진행중인 상태 | |
| 일 다시 시작하기 | 퇴근 상태 | |
| 일 시작하기 | 출근 안 한 상태 | 기본값(default) |
| 휴식이 진행중인 상태 | ||
| 퇴근 상태가 아니지만, 출근한 상태 |
마크다운이라 셀 합치기는 못 했지만, ‘일 시작하기’에 해당하는 여러 상태와 비고를 확장 가능한 형태로 표현할 수 있어서 보기도 편합니다.
ChatGPT와 함께라면 어렵지 않습니다
개인적으로 Mermaid를 잘 익혀보고 싶은데, ChatGPT가 너무 잘 그려주다 보니 아직 혼자서는 Mermaid 코드를 작성하지 못하는 단계에 머물러 있습니다.
아래는 예시1의 Mermaid 코드를 ChatGPT에게 작성시킨 대화입니다. 완벽하게 호환되지는 않고, 일부 syntax에 맞지 않는 이름을 수정해줘야 합니다. 대표적으로 코드에 ( 같은 문자가 들어가면 mermaid.live에서도 에러가 발생하므로, 그 정도는 직접 수정해야 합니다.
코드를 그냥 넘겨도 잘 작성해줍니다. 다만 ChatGPT가 가끔 상상력을 발휘해서 다른 코드를 끼워넣는 경우가 있으므로, 결과물은 반드시 직접 확인해야 합니다.
이 부분은 약간 아쉬웠습니다.
여튼 이렇게 ChatGPT로 잘 뽑아낼 수 있습니다.
