문제
같은 정책이 레포와 협업 위키 두 곳에 있었습니다. 원칙은 정본이 레포라는 것이었고, 정본은 고치는 자리가 하나뿐인 기준을 말합니다. 그런데 비개발 직군은 레포를 상시 보는 동선이 아니었습니다. 그들이 실제로 여는 곳은 위키였고, 위키 문서에는 그것이 사본이라는 표시가 없었습니다.
그래서 옛 값이 확신을 갖고 인용됐습니다. 한 번은 이미 바뀐 기간 값이 사본에 남아 있었고, 읽는 사람에게는 그것이 낡았다는 것을 알 방법이 없었습니다. 사본은 틀린 값을 말하고 있다는 신호를 전혀 내지 않습니다.
판단
미러를 없애는 방향은 이미 한 번 실패했습니다. 사람들이 보는 곳을 금지한다고 해서 동선이 바뀌지는 않습니다. 그래서 반대로 갔습니다.
미러를 공식 절차로 편입했습니다. 정본을 신설하면 같은 작업 안에서 미러를 만듭니다. 대신 세 가지를 걸었습니다.
- 미러는 요약이지 복제가 아닙니다. 전문을 복사하면 두 벌이 되고 두 벌은 반드시 갈립니다. 요약은 애초에 원본을 보러 가게 만듭니다
- 상단에 정본 경로와 동기화 날짜 배너를 고정합니다. 배너가 없으면 미러가 곧 정본으로 읽힙니다. 옛 값 사고가 정확히 이 경로로 났습니다
- 정본을 고치면 미러도 같은 작업 안에서 대조합니다. 반쪽 갱신은 미러를 아예 안 만드는 것보다 나쁩니다. 갱신이 끊긴 미러는 옛 값을 확신을 갖고 들고 있습니다
인용 입구를 하나로
두 번째 문제는 인용이었습니다. "기준이 어디냐" 에 답이 여러 개면 인용하는 사람마다 다른 곳을 엽니다. 비개발 직군이 우리 기준을 인용할 때 여는 곳을 단 하나의 입구로 고정했습니다. 그 아래 항목이 몇 개든 입구는 하나입니다.
대가는 정직하게 적어 두었습니다. 그 목록은 자동 등재가 아니라 수기 유지입니다. 정책을 신설하면 등재가 같이 가야 하고, 등재를 빠뜨리면 그 정책은 인용하는 사람에게 "기준에 없는 것" 이 됩니다. 자동화하지 못한 자리를 자동화한 척하지 않는 것이 이 설계에서 제일 중요한 부분이었습니다.
정책에 들어가는 숫자도 문서 본문에 박지 않았습니다. 별도 목록을 단일 출처로 두고 화면들이 그것을 읽게 했습니다. 숫자가 여러 문서에 흩어지면 바뀔 때 반드시 몇 곳이 남고, 남은 쪽이 더 자주 인용됩니다.
반복되는 실수는 문장이 아니라 검사로
문서 체계를 세우고 나서 같은 문제를 다른 자리에서 다시 만났습니다. 같은 실수가 두 번째로 나면 문서에 주의 문장을 한 줄 추가하는 것이 기본 대응이었습니다. 그렇게 몇 달이 지나면 주의 문장만 수백 줄이 쌓이고, 그 문서는 아무도 끝까지 읽지 않습니다. 더 나쁜 것은 그 줄들이 언제 쓸모없어졌는지 아무도 모른다는 점입니다.
그래서 반복 실수를 문장으로 쌓지 않고 기계가 잡는 검사로 옮기는 절차를 만들었습니다. 캡처, 분류, 승격, 회수 네 단계입니다. 승격이 끝나면 원래 문장은 포인터 한 줄로 줄이거나 지웁니다. 검사가 잡는 것을 문장으로 또 적어 두면 그 문장은 순수한 비용입니다. 발동 조건도 정해 두었습니다. 재발 두 번째, 사고 한 번째, 그리고 기준 문서와 실제가 어긋난 것을 발견했을 때입니다.
회수를 절차에 넣은 것이 핵심입니다. 이런 대장은 대부분 한 방향으로만 자랍니다. 추가할 이유는 매번 생기고 지울 이유는 아무도 만들지 않기 때문입니다. 그래서 주기적으로 이 문서를 다시 읽고 더 이상 발동하지 않는 줄을 걷어냅니다. 문서가 일정 분량을 넘는 것 자체도 발동 조건으로 넣어, 길이가 곧 신호가 되게 했습니다.
검사가 잡지 못하는 것을 정직하게 적었습니다
가드를 붙이면서 같이 배운 것은, 검사가 있다는 사실이 커버리지를 뜻하지 않는다는 것이었습니다.
- 어떤 검사는 지정된 목록 안에서만 돕니다. 목록에 없는 화면은 초록불인 채로 옛 값을 들고 있습니다
- 어떤 검사는 차단이 아니라 경고입니다. 경고는 막지 않으므로 사람이 결과를 열어야 합니다. 열지 않으면 없는 것과 같습니다
- 어떤 검사의 대조 목록은 수기 유지입니다. 기준 값을 바꾸면 검사 쪽 목록도 같은 작업에서 고쳐야 합니다. 실제로 확인해 보니 목록 대부분이 옛 값이었습니다
셋 다 문서에 명시했습니다. 검사가 있다는 것과 지켜지고 있다는 것을 구분해 적지 않으면, 초록불이 오히려 확인을 멈추게 만듭니다.
결과
문서가 늘어나는 것을 막는 대신, 늘어난 문서가 자기 위치를 스스로 말하게 했습니다. "어느 쪽이 최신인가" 라는 질문이 문서를 여는 순간 화면에서 답해집니다. 그리고 주의 문장으로 유지하던 규칙 상당수가 커밋 시점과 작성 시점에 자동으로 걸리는 검사로 옮겨졌습니다. 사람이 기억해야 하는 목록이 줄어든 만큼, 남은 목록은 실제로 사람이 판단해야 하는 것들만 남았습니다.