배포 — QA 위젯

남의 기계에 도구를 올리는 일이 도구를 만드는 일보다 어려웠습니다.

남의 기계에 도구를 올리는 일이, 도구를 만드는 일보다 어려웠습니다.

혼자 쓸 때는 없던 문제들

제 컴퓨터에서는 잘 돌았습니다. 팀에 나눠 주니 코드는 그대로인데 안 도는 기계가 생겼습니다.

원인이 코드에 없습니다. 환경에 있습니다 — 뭔가가 안 깔려 있거나, 권한이 없거나, 경로가 다르거나.

처음엔 설치 안내 문서를 줬습니다. 「이거 받고, 여기 넣고, 이 값을 채우세요」.

그리고 정확히 같은 일이 났습니다.

문서는 읽어야 하고, 아무도 안 읽습니다.

이 위젯을 만든 이유가 「대시보드는 보러 가야 하고 아무도 안 간다」였는데, 배포에서 같은 실수를 반복한 것입니다.

그래서 문서를 «설치 프로그램»으로 바꿨습니다. 실행하면 알아서 확인하고 채우고, 안 되면 무엇이 안 됐는지 한 줄로 말합니다.

설치 프로그램이 길게 설명하지 않습니다. 항목마다 되는지 안 되는지만 말합니다.

왜 이 형식이냐면 — 안 되는 사람은 대개 「어디가 문제인지」만 알면 됩니다. 긴 설명은 되는 사람에게는 필요 없고, 안 되는 사람에게는 어차피 안 읽힙니다.

팀원이 쓸 때 각자 자기 계정의 열쇠를 넣습니다. 공용 계정 하나로 안 돌립니다.

편하기로는 공용이 훨씬 편합니다. 한 번 설정하고 다 같이 쓰면 됩니다.

안 그런 이유가 둘입니다.

이유
권한이 사람마다 다름	공용 계정을 쓰면 자기가 볼 권한 없는 것까지 보게 됨
누가 했는지가 안 남음	전부 공용 계정 이름으로 기록됨

두 번째가 특히 나쁩니다. 나중에 「이거 누가 바꿨지?」에 답할 수가 없습니다.

경계가 명확해야 안내가 짧아집니다.

이 표가 있으면 설치 안내가 「위의 둘은 제가 드리고, 아래 둘은 본인 것을 넣으세요」 한 줄로 끝납니다.

경계가 흐리면 안내가 길어지고, 안내가 길어지면 안 읽힙니다. 그리고 안 읽히면 처음 문제로 돌아갑니다.

혼자 쓸 때는 없던 문제가 팀에 뿌리면서 전부 나왔다. 코드는 그대로인데 안 도는 기계가 생긴다.

처음엔 안내 문서를 줬다. 그리고 이 위젯을 만든 이유와 똑같은 일이 벌어졌다 — 문서는 읽어야 하고, 아무도 안 읽는다.

그래서 셋업 스크립트를 만들었다. 돌리면 항목마다 OK / NG를 찍고, NG면 무엇을 어떻게 채워야 하는지 말한다. 전부 OK가 될 때까지 돌리면 된다.

문서에 “이 파일을 여기에 두세요”라고 적는 것과, 스크립트가 “이 파일이 없습니다”라고 말하는 것은 도달률이 다르다. 앞의 것은 읽는 사람이 자기 상태와 대조해야 하고, 뒤의 것은 대조가 이미 끝나 있다.

팀원이 쓸 때 각자 자기 계정의 토큰을 넣는다. 공용 계정 하나로 돌리지 않는다.

그래서 시트 열람 권한이 없는 사람에게는 데이터가 안 뜬다. 이건 버그가 아니라 의도다 — 위젯이 볼 권한 없는 것을 보여주는 통로가 되면 안 된다.

공용 계정으로 만들었으면 셋업이 훨씬 쉬웠을 것이다. 토큰 하나 나눠 주면 끝이니까. 그런데 그렇게 하면 누가 무엇을 봤는지가 전부 그 계정 하나로 뭉개지고, 나중에 권한을 회수할 방법도 없다.

다만 개인별로 두면 셋업 단계가 하나 늘고, 그게 위의 스크립트가 필요했던 이유이기도 하다.

경계가 명확해야 안내가 짧아진다.

이 표를 문서 맨 앞에 두는 것만으로 질문이 절반 줄었다. 안 두면 “토큰 주세요”가 오는데, 어느 토큰인지가 안 붙어 있다.

그리고 공용 토큰은 저장소에 올리지 말라고 명시해 뒀다. 개인 설정 파일이 저장소 밖에 있어야 하는데, 안 적어 두면 편의상 같이 커밋하는 사람이 반드시 나온다.