화면이 없어진 기능을 설명하고 있었다

서비스 소개 페이지의 기능 카드에 이렇게 적혀 있었습니다.

통합검색 — 상세검색, 기관·유형·태그 필터로 원하는 데이터를 찾을 수 있습니다.

그 필터들은 없습니다. 통합검색은 그새 탭별 결과 + 분류 칩 구조로 바뀌었어요. 다른 카드도 마찬가지였습니다.

정보 조회 — 연관 카테고리 중심 구조로 …

지금은 클래스 구성 속성·연결 자원 표현입니다.

기능 코드는 계속 고치는데 그 기능을 설명하는 화면은 아무도 안 고칩니다. 테스트가 안 잡고, 리뷰에도 안 걸리고, 개발자는 소개 페이지를 안 봐요. 그래서 소개 페이지는 개발이 멈춘 시점에 그대로 얼어 있었습니다.

도입 배경이 몇 년 전 문서였다

더 심한 건 도입 배경 절이었습니다. 4차 산업혁명·D.N.A·ICBM·센서 — 몇 년 전 제안서 문체 그대로였어요. 지금 이 시스템이 왜 필요한지를 설명하지 못합니다.

국22 RFP의 '연구개발 필요성' 서사로 갈아 끼웠습니다. 줄기가 이렇습니다.

문서 배포 표준 → 명칭·형식이 제각각 → 메타데이터 기반 공개 시스템

이게 실제로 이 시스템이 푸는 문제입니다. 표준을 PDF로 배포하면 쓰는 쪽에서 이름과 형식이 갈리고, 그러면 데이터를 주고받을 수가 없어요. 그래서 표준을 데이터로 공개하는 시스템을 만든 겁니다. 한 문장으로 설명되는 걸 그동안 유행어로 덮고 있었습니다.

방법	장점	포기하는 것	판단
① 틀린 문구만 찾아 교체	빠름. 리스크 없음	구조가 그대로 남음 — 기능 카드 나열 뒤에 CTA. "왜 필요한가"가 여전히 없음	기각
② 구조까지 재구성 (채택)	서사가 생김. 처음 온 사람이 읽고 이해	분량이 커지고, 다음에 또 낡음	채택
③ 소개 페이지를 없애고 이용 가이드로 통합	유지할 화면이 하나 줄어듦	소개는 "무엇인가", 가이드는 "어떻게 쓰는가" — 독자가 다름. 로그인 전 방문자가 갈 곳이 없어짐	기각

②로 갔습니다. 대신 다음에 또 낡는다는 걸 전제로, 화면이 서술하는 기능마다 어느 화면을 가리키는지 명시했어요. 다음 사람이 대조할 수 있게요.

신설한 절:

히어로 — 시스템 정의문 한 문장 + CTA + CSS로 만든 화면 목업
주요 관리 대상 — 표준데이터 중심 허브-스포크 관계도. 전에는 표준데이터 카드 자체가 빠져 있었습니다(이 시스템의 주인공이 소개에서 누락)
데이터 이해와 활용을 돕는 서비스 — 데이터 시각화, ASN.1 AI 도우미
표준데이터가 서비스로 이어지는 과정 — 5단계
이런 분들이 활용할 수 있습니다 — 역할 3종

하단에 있던 이용 가이드 CTA 박스는 지웠습니다. 히어로에 이미 CTA가 있어서 같은 버튼이 두 번 나왔어요.

안 쓴 것을 정하는 게 절반이었다

소개 페이지에서 의도적으로 뺀 것이 셋입니다.

Open API — 코드가 아직 병합 전
물리 아키텍처 — 메뉴가 아직 비공개
시험시스템 — 별도 시스템이라 여기서 설명할 대상이 아님

"곧 나올 것"을 소개에 미리 쓰면, 방문자는 찾다가 못 찾습니다. 소개 페이지의 신뢰는 있는 걸 다 쓰는 게 아니라 없는 걸 안 쓰는 데서 나온다고 봤어요. 뺀 이유는 이력 문서에 남겼습니다.

용어도 실제 시스템 기준으로 맞췄습니다. 역할명은 신청자·관리자·심의위원회(이 시스템에 실제로 있는 역할), "데이터엘리먼트", "자율주행 Lv.4". "누구나" → "언제 어디서든"으로 바꾼 것도 사실 확인이었어요 — 일부 기능은 로그인이 필요해서 "누구나"가 아닙니다.

이용 가이드 — 슬라이드를 실제 화면 순서로

이용 가이드는 캐러셀입니다. 슬라이드 순서가 실제 사용 흐름과 달랐어요. 사용자가 하는 순서대로 다시 짰습니다.

통합검색 → 표준데이터 → 카탈로그 → 분류체계 → 상세 → 신청 작성 → 제출 후 → 심사

심사 슬라이드는 새로 만들었습니다. 신청하면 심의위원회가 본다는 걸 가이드가 한 번도 말한 적이 없었어요.

각 슬라이드에 세 가지를 붙였습니다.

접근 배지 — 비로그인 / 로그인 / 심의위원회 권한. 로그인 없이 되는 게 뭔지 미리 알려줍니다
GNB 메뉴 경로 칩 — 글로 "표준데이터 화면에서"라고 쓰면 그 메뉴를 못 찾아요
기대 결과 / 잘 안 될 때 박스

"잘 안 될 때" 를 넣은 게 이 작업에서 제일 나은 판단이었다고 봅니다. 가이드는 보통 성공 경로만 그리는데, 사용자가 가이드를 여는 건 대개 안 될 때거든요.

여기서 실제 오류도 하나 잡았습니다. OID 예시가 틀려 있었습니다.

잘못: 세계 / 아시아 / … / 200046
실제: ISO / member-body / … / itskorea 200053

OID는 계층 구조에 의미가 있어서, 예시가 틀리면 개념 자체를 잘못 배웁니다. 문서에서 숫자만 옮겨 적다 생긴 오류로 보이는데, 예시야말로 원본과 대조해야 하는 부분이었어요.

용어 카드는 6장에서 4장으로 줄였습니다. 개념 공유 문서와 대조해보니 두 장이 같은 걸 다르게 말하고 있었습니다.

캡처 12장도 다시 찍었습니다. 인스턴스 상세·카탈로그 트리·심사 화면이 전부 개편 전 모습이었어요. 촬영 스펙(대상 데이터 ID, 목록·카탈로그 URL)도 같이 갱신했습니다 — 스펙을 안 고치면 다음 촬영 때 또 옛 URL로 찍습니다.

이틀 전에 적은 규칙을 뒤집었다

같은 축에서 하나 더 했습니다. 읽기 전용 화면의 의무 수준 표기(필수 * / 권장 칩) 제거입니다.

경위가 이렇습니다.

8/3 오전 — 공개 표준데이터 상세에서 권장 칩만 숨김. 커밋 메시지에 "필수 * 표기만 유지"라고 적음
8/3 오후 — 그 결정을 뒤집고 세 등급 전부 읽기 전용에서 제거

오전 판단의 근거는 "카탈로그 트리 패널과 표기 규칙 일치"였습니다. 그런데 오후에 다른 화면들을 훑다 보니 일치시킬 기준 자체가 틀렸다는 게 보였어요.

필수 *와 권장 칩은 작성 유도용 표기입니다. "이 칸을 채우세요"라는 말이에요. 이미 저장된 값을 보여주는 읽기 전용 화면에서는 할 말이 아닙니다. 값이 거기 있는데 "필수입니다"라고 말해봐야 아무 행동도 유발하지 않아요.

기준을 "작성 유도인가" 로 다시 잡으니 권장만 뺄 이유가 없었습니다. 대상이 5곳으로 늘었어요.

공개 인스턴스 상세
카탈로그·분류체계·데이터셋 트리 패널
데이터 맵 속성 잎
공개 클래스 상세 용어명
해당 범례 문구

공개 클래스 상세는 특히 명확했습니다. 필수 여부 (Obligation) 열이 이미 값을 내고 있는데 이름 옆에 *를 또 붙이고 있었어요. 같은 정보가 두 번입니다.

지우면서 조심한 게 하나 있습니다. conceptClassTree.js의 REQUIRED_MARKUP 상수는 같은 파일의 카테고리 입력 폼이 씁니다. 입력 폼은 작성 유도가 맞으니 남겨야 해요. 상수는 두고 읽기 표 쪽 호출만 제거했습니다. 상수까지 지웠으면 입력 폼의 표기가 조용히 사라졌을 겁니다.

그리고 오전 커밋이 깨뜨린 회귀 스펙 1건이 방치돼 있었습니다. 권장 칩을 기대하던 스펙인데, 오전에 빨개진 채로 뒀던 거예요. 이번에 반대 방향으로 재작성했습니다 — 세 등급 모두 무표기인지 확인하도록. 규칙 정본은 metadata-data-model.md 6.1로 옮기고, UI 문서에는 뒤집힌 표시(🔄)를 달았습니다.

문서 언어를 독자 기준으로 갈랐다

문서 정리를 하다 보니 영어 문서 안에 한국어 UI 용어가 박혀 있는 상태가 많았습니다. docs/ 문서는 화면을 설명하니 "표준데이터", "분류 칩", "필수 여부" 같은 말이 계속 나오는데, 서술은 영어라 한 문장 안에서 언어가 섞였어요.

읽는 사람 기준으로 갈랐습니다.

문서	언어	근거
에이전트용(`CLAUDE.md`, 스킬 정의)	영어	도구가 읽음
`docs/`	한국어	사람이 읽고, 본문에 한국어 UI 용어가 이미 박혀 있음

식별자·경로·클래스명·Tailwind 토큰은 코드로 봐서 원형을 유지합니다.

기존 영어 문서를 일괄 번역하지는 않기로 했습니다. 한 번에 다 뒤집으면 diff가 거대해져서 리뷰가 불가능하고, 번역 과정에서 내용이 조용히 바뀌어도 아무도 못 봐요. 손대는 김에 한 건씩 전환하는 방식으로 명시했습니다. 이번에 한 건(request-form-unification.md)만 옮겼고, 한글 비율이 2% → 49% 가 됐습니다.

검증

소개 페이지 서술 대 실제 화면 대조 — 기능 카드 2종의 구 화면 표현을 현행화. 소개가 말하는 기능이 실제로 그 화면에 있는지 하나씩 열어봤습니다.
OID 예시를 표준 문서와 대조해 정정(200046 → itskorea 200053).
용어 카드 6 → 4장, 개념 공유 문서와 정합 확인.
캡처 12장 재촬영, 촬영 스펙 현행화.
의무 수준 표기 제거 대상 5곳. 깨진 채 방치돼 있던 회귀 스펙 1건을 반대 방향으로 재작성 — 세 등급 모두 무표기 확인.
문서 이력(system-usage-guide-history.md Phase 4)에 뺀 항목과 이유 기록.

남은 것 · 한계

소개 페이지는 또 낡습니다. 이번에 구조를 잡았을 뿐이고, 기능이 바뀌면 여전히 아무도 안 고쳐요. 화면 서술과 실제 화면을 잇는 자동 검사가 없습니다. e2e로 "소개 페이지가 말하는 메뉴 경로가 실제로 존재하는가" 정도는 잠글 수 있을 텐데 안 했습니다.
Open API·물리 아키텍처는 뺐지만 언제 넣을지 없습니다. 병합·공개 시점에 소개를 고쳐야 하는데, 그 연결이 사람 기억에만 있어요.
문서 언어 전환은 "손대는 김에" 라 대부분의 영어 문서가 그대로입니다. 한동안 두 언어가 섞인 상태가 계속됩니다. 의도한 타협이지만 새로 온 사람에게는 일관성 없음으로 보일 거예요.
의무 수준 표기 규칙은 문서에만 있습니다. 새 읽기 전용 화면에서 *를 다시 붙여도 아무것도 안 막아요. 회귀 스펙이 잠근 건 기존 5곳뿐입니다.