옛 자료의 고유 용어를 정의해 뒀다

문서와 코드에 차수 라는 말이 계속 나왔는데 그것이 무엇인지 몰랐다.

Open Table of contents

증상 — 사전에 없는 말
원인 — 두 말이 달랐다
결과 — 용어집을 만들었다
주의 — 가장 자주 참조된 항목
제약 — 시기에 따라 바뀐 뜻
재발 방지 — 자리와 유지
정리

증상 — 사전에 없는 말

이런 식으로 쓰이고 있었다.

차수별 수강생 목록
차수 마감
차수 생성

차수 는 일반적인 말이 아니라 그 조직에서만 쓰는 말이었다.

물어보니 같은 과정을 여러 번 여는데 그 회차라고 했다.

과정: 실무 데이터 분석
  1차수  2019-03-01 ~ 2019-04-30  수강생 30명
  2차수  2019-05-01 ~ 2019-06-30  수강생 28명

코드에서는 Session 이었다.

찾아보니 이런 말이 여럿이었다.

차수    같은 과정의 회차
개강    차수가 시작되는 것
이수    수료 조건을 채운 것
수료    이수 후 수료증이 발급된 것
청강    등록하지 않고 듣는 것

물어본 것을 적어 두지 않으면 몇 주 뒤에 또 물어보게 된다.

원인 — 두 말이 달랐다

이수 와 수료 가 다른 것이 특히 헷갈렸다.

SELECT COUNT(*) FROM enroll WHERE completed = 'Y';        -- 이수
SELECT COUNT(*) FROM certificate WHERE issued = 'Y';      -- 수료

completed 를 채운 것과 issued 가 나간 것이 달라 숫자도 달랐다.

completed 인데 수료증을 안 받은 사람이 있었다. 두 말이 서로 다른 값을 가리키는데 사람들이 섞어 쓰고 있어서 집계가 안 맞는다는 문의의 원인이 되고 있었다.

결과 — 용어집을 만들었다

정리한 것을 glossary.md 한 문서에 모았다.

[차수] Session
  같은 과정을 여러 번 여는 각 회차. 과정 1개에 차수 여러 개.
  DB: tb_session, 코드: Session

[이수] Completed
  수료 조건(출석률 80%, 평가 60점 이상)을 채운 상태.
  DB: tb_enroll.completed = 'Y'

[수료] Certified
  이수 후 수료증이 발급된 상태. 이수와 다르다.
  이수했으나 수료증 미발급인 경우가 있다 (신청을 안 한 경우).
  DB: tb_certificate.issued = 'Y'

한국어 말과 코드 이름과 DB 자리를 같이 적었다.

셋을 오갈 수 있어야 했다. 화면에서 본 말로 코드를 찾고 코드에서 본 이름으로 표를 찾는 일이 계속 생긴다.

주의 — 가장 자주 참조된 항목

헷갈리는 것에는 주의 항목을 따로 적었다.

[주의]
  이수와 수료를 같은 것으로 세지 않는다
  "수강생 수"는 문맥에 따라 다르다
    등록자 수 (취소 포함)
    실수강자 수 (취소 제외)
    이수자 수
  화면·보고서마다 어느 것인지 확인한다

이 주의 항목이 가장 자주 참조됐다.

통계 숫자가 안 맞는다는 문의가 대부분 여기서 갈렸다. 뜻은 한 번 읽으면 남는데 그 예외들은 매번 다시 확인하게 된다.

제약 — 시기에 따라 바뀐 뜻

시기에 따라 뜻이 바뀐 말도 있었다.

2017년 이전  "수료" = 지금의 "이수"
2018년부터   수료증 제도가 생기면서 분리

옛 문서의 수료 200명은 지금 기준으로 이수 200명이었다.

[시기별 차이]
  2018-01 이전 문서의 "수료"는 지금의 "이수"를 가리킨다.
  그 이전 통계와 지금 통계를 비교할 때 주의한다.

이것을 안 적으면 옛 통계와 지금 통계를 그냥 비교하게 된다.

재발 방지 — 자리와 유지

glossary.md 를 코드 저장소에 넣었다.

docs/glossary.md

코드와 같은 자리에 두니 코드를 고칠 때 눈에 들어왔고 별도 문서 도구에 두면 안 본다.

새 개념이 생길 때의 순서도 정했다.

새 개념이 생기면
  1. 한국어 이름을 정한다
  2. 영문 표기를 정한다 (기존 것과 안 겹치는지 본다)
  3. glossary.md 에 적는다
  4. 그 뒤에 코드를 쓴다

셋째를 넷째보다 먼저 둔 것은 이름을 안 정하고 코드를 쓰면 이름이 코드에서 정해지기 때문이다.

화면 문구도 glossary.md 를 따르게 했다.

"수료 현황"        실제로는 이수 현황
"완료된 강의"      실제로는 이수한 차수
"과정 목록"        실제로는 차수 목록

수료 현황 과 완료된 강의 와 과정 목록 이 다 다른 것을 가리키고 있었다.

문구를 바꾸면서 문의가 늘 것을 걱정했는데 반대였다. 이게 뭐냐는 문의가 줄었고 문구를 한 자리에 모아 두니 용어집과 대조하기도 쉬웠다.

정리

그 조직에서만 쓰는 말은 정의해 두지 않으면 다음 사람이 모른다
물어본 것을 적어 두지 않으면 또 물어보게 된다
비슷해 보이는 두 말이 다른 것을 가리킬 수 있다
그것이 숫자가 안 맞는 원인이 된다
한국어 말과 코드 이름과 DB 자리를 같이 적는다
주의 사항이 가장 자주 참조된다
시기에 따라 뜻이 바뀐 말을 적는다
옛 통계와 비교할 때 그것이 필요하다
용어집을 코드와 같은 자리에 둔다
새 개념은 이름을 먼저 정하고 코드를 쓴다
화면 문구도 용어집을 따르게 한다