docs/design/ 아래 설계 문서를 쓰면서 결정하지 못한 것을 남겨 두고 다음 문서로 넘어갔다. 다음 문서에서는 그 미결에 대해 가정을 세우고 썼는데 나중에 다른 쪽으로 정해졌다.
Table of contents
Open Table of contents
미결 위에 쌓인 것
auth.md에 미결이 둘 있었고 client.md가 그중 하나에 대해 가정을 세웠으며 server.md가 client.md에 의존했다.
미결 하나가 예상과 다르게 정해지자 그 위에 쌓인 문서가 전부 흔들렸다. 미결을 남기고 가면 그 위에 쌓인 것이 전부 그 미결의 답에 걸려 있게 된다.
조치 — 닫고 가는 순서
그래서 순서를 정했다. 미결을 OPEN-QUESTIONS.md 목록으로 만들고 조사로 닫을 수 있는 것은 조사하며 물어봐야 하는 것은 한 번에 묻고 답이 올 때까지 그것에 의존하는 문서는 쓰지 않는다.
여기서 마지막 항목이 중요했다. 전부 멈추는 것이 아니라 그 미결에 의존하지 않는 문서는 계속 쓴다. depends:를 따라 의존 관계를 먼저 그려 보면 대기해야 하는 것과 진행할 수 있는 것이 갈린다.
대응 — 의존 관계의 기록
각 문서 머리의 frontmatter에 depends: [auth-method]처럼 무엇에 의존하는지를 적었다. 그 미결이 닫히면 이 문서를 다시 봐야 한다는 것이 드러난다.
미결이 닫혔을 때 어느 문서를 고쳐야 하는지도 grep -rl "depends:.*auth-method" docs/로 찾을 수 있었다. 실제로 인증 방식이 정해졌을 때 의존한다고 적어 둔 client.md·server.md 둘을 찾아 고치고 미결 목록에서 지웠다. 적어 두지 않았으면 어느 문서가 그 결정에 걸려 있었는지 기억에 의존하게 된다.
미결 목록 자체도 OPEN-QUESTIONS.md 한 파일에 뒀다. 문서마다 흩어져 있으면 못 찾고, 한 화면에 모아 두니 오래 대기 중인 것이 드러나 닷새를 넘기면 다시 물었다.
답이 늦을 때의 가정
물어봤는데 답이 안 오는 경우에 두 가지 방법이 있었는데 답이 올 때까지 의존하는 문서를 멈추는 것과 가정을 세우고 진행하는 것이다. 뒤쪽을 골랐다. 이유는 의존하는 문서가 둘이라 멈추면 그 주 작업이 서서다. 대신 가정이 틀리면 되돌리는 비용을 감수했고 그래서 [가정] 표지와 함께 무엇이 영향받는지를 적었다.
[가정] 토큰 방식으로 진행한다 (2025-02-01)
근거: 다른 연동이 토큰을 쓴다. 키 방식이면 알려 주십시오.
영향: 키 방식으로 바뀌면 클라이언트 설계 3절, 서버 설계 2절을 다시 본다바뀌었을 때 어디를 봐야 하는지 알고 있으니 되돌리기가 쉬웠다. 가정을 세우는 것과 미결을 잊는 것은 다르고 그 차이가 영향 범위를 적었는지에 있다.
물어보는 방식
두 주가 지나도 답이 안 오는 것이 있어서 물어보는 방식을 바꿨다. 무엇으로 할지 고르라는 열린 질문 대신 어느 쪽으로 진행하겠고 다르면 언제까지 알려 달라는 통지로 바꿨고 OPEN-QUESTIONS.md에도 그 기한을 적었다.
답이 며칠 만에 왔다. 고르는 것보다 확인하는 것이 답하기 쉽기 때문이다. 고를 것이 여럿이면 하나를 추천하고 그 이유를 함께 적었다.
물어보는 방식이 답이 오는 속도를 바꿨고 그것이 미결이 열려 있는 기간을 정했다.
정리
- 미결을 남기고 가면 그 위에 쌓인 것이 흔들린다
- 미결을
OPEN-QUESTIONS.md목록으로 만들고 조사로 닫을 것과 물어볼 것을 가른다 - 전부 멈추지 않고 의존하지 않는 것은 진행한다
- 문서 머리에
depends:로 무엇에 의존하는지 적는다 - 답이 늦으면
[가정]을 세우되 영향 범위를 함께 적는다 - 가정을 세우는 것과 미결을 잊는 것의 차이가 거기 있다
- 미결 목록을 한 자리에 두고 오래 대기하는 것을 본다
- 물어보는 방식이 답이 오는 속도를 바꾼다