공개: KoTalk 최신 기준선

문서/34-current-limitations-and-doc-drift.md

@@ -0,0 +1,112 @@
+# Current Limitations And Doc Drift
+
+## 목적
+
+프로젝트가 커질수록 가장 위험한 것은 부족한 기능 자체보다 `이미 된 것처럼 보이는 상태`다.  
+이 문서는 현재 산출물의 한계와 문서-구현 간 드리프트를 의도적으로 드러내기 위해 작성한다.
+
+## 왜 필요한가
+
+- 오픈소스 저장소는 README와 문서가 좋아질수록 실제보다 더 성숙해 보일 수 있다.
+- 하지만 메신저는 실제 사용의 신뢰가 중요하므로, 과장된 인상을 방치하면 오히려 역효과가 난다.
+- 이 문서는 내부 경계 장치다.
+
+## 현재 한계
+
+### 1. 세션 연속성
+
+- 문서에는 세션 복구와 연속성 방향이 정리되어 있다.
+- 그러나 실제 현 산출물에서는 리프레시/재복구 체감이 충분하지 않다.
+- 라이브 웹에서 `401` 노출이 관찰된 이상, 현재는 `세션 신뢰 취약`으로 분류한다.
+
+### 2. 검색과 재발견
+
+- 일부 로컬 필터 수준의 검색은 있으나, 제품 우위로 주장할 만한 전역 검색은 아직 없다.
+- 문서에서 검색이 큰 축을 차지하는 만큼, 실제 구현 격차를 분명히 적어야 한다.
+
+### 3. 드래프트/전송 신뢰
+
+- 초안 보존 방향은 있으나, 사용자 체감상 `정말 안 날아간다`는 확신을 줄 정도는 아니다.
+- 전송 실패 후 인라인 재시도 경험도 성숙하지 않다.
+
+### 4. Windows 생산성
+
+- 화이트/플랫/컴팩트 UI는 정리됐지만 팝아웃, 전역 검색, 고정 슬롯, 안 읽은 허브 등 핵심 생산성 장치는 아직 설계 우위가 크다.
+
+### 5. Mobile Web 안정감
+
+- 실제 작은 화면에서 레이아웃 안정성 문제가 있으면 전체 품질 인상이 무너진다.
+- 라이브 환경에서 발견된 오버플로는 단순 CSS 버그가 아니라 제품 신뢰 문제로 취급해야 한다.
+
+### 6. 공개 배포 표면
+
+- 다운로드 호스트와 원격 Releases가 `실제로 누구나 바로 받을 수 있는가` 관점에서 아직 마감되지 않았다.
+- 문서상 채널 구조와 실사용 접근성이 동일하지 않을 수 있다.
+
+## 문서-구현 드리프트 사례
+
+### 사례 A. 검색
+
+- 문서상 `검색 미구현`처럼 보이는 표현과, 실제 일부 로컬 검색 기능 존재가 섞여 있다.
+- 해결:
+  - `로컬 기본 검색`
+  - `전역 검색`
+  - `자료 검색`
+로 명칭을 분리한다.
+
+### 사례 B. 보안 저장
+
+- 문서 일부는 보다 강한 보안 저장을 전제로 읽힐 수 있다.
+- 실제는 플랫폼별 임시 저장 구조가 더 단순하다.
+- 해결:
+  - 문서에 현재 저장 모델을 정확히 명시
+  - 목표 상태와 현재 상태를 분리 표기
+
+### 사례 C. 세션 복구
+
+- 문서에서는 복구 흐름이 잘 설계돼 있지만, 실제 서비스에서는 실패 흔적이 보인다.
+- 해결:
+  - `설계됨`과 `검증됨` 상태를 분리
+
+### 사례 D. Windows 멀티윈도
+
+- 문서는 다중 창 전략을 자세히 다루지만, 구현은 아직 도달하지 못했다.
+- 해결:
+  - README에서는 약속보다 상태를 우선 표기
+
+## 앞으로 문서를 쓸 때의 규칙
+
+- `지원` 대신 `계획`, `부분 구현`, `라이브 검증 완료` 같은 표현을 구분한다.
+- 스크린샷이 있어도 실사용 검증과 동일시하지 않는다.
+- 릴리즈 가능한 기능과 내부 데모용 기능을 혼합해서 말하지 않는다.
+- 현 시점 한계 문서를 매 주요 릴리즈마다 갱신한다.
+
+## 사용자 관점에서 특히 위험한 드리프트
+
+- 보기엔 다 된 것 같은데 실제로는 자주 끊기는 세션
+- 홍보상으로는 업무 효율 우위인데 실제로는 검색이 약한 상태
+- 다운로드가 가능하다고 써 있지만 접근이 매끄럽지 않은 상태
+- 안정감 있는 메신저처럼 보이지만 실사용 중 오류가 보이는 상태
+
+이 네 가지는 사용자의 기대를 가장 크게 배반한다.
+
+## 릴리즈 전 체크리스트
+
+- README 상태 표는 실제와 일치하는가
+- 문서의 `가능` 표현이 실제 빌드/배포/사용 상태와 맞는가
+- 라이브 URL에서 핵심 루프를 직접 확인했는가
+- 최신 스크린샷이 현재 UI와 맞는가
+- 다운로드 경로가 실제로 작동하는가
+
+## 관리 책임
+
+- 기능 문서 작성자
+- 실제 구현 담당자
+- QA 검증자
+
+세 역할이 다를 수 있으므로, 최소한 릴리즈 직전에는 교차 확인이 필요하다.
+
+## 완료 기준
+
+- 이 문서가 불편할수록 프로젝트는 건강해진다.
+- 저장소가 보기 좋아질수록, 현재 한계를 더 명확히 쓰는 습관이 필요하다.