docs: rewrite README for public launch + direct portal search links#17
Merged
Conversation
Total rewrite optimized for first-time external users about to discover the project via HACS Default + community posts. Prior README was 860 lines and information-dense; new version is 523 lines with stronger first-impression and direct deep links to each portal's search page (the part users most need but other Korean HA integrations rarely provide). Key changes: 1. **Hero rewrite** — one-line value proposition + collapsible English summary for expat / international readers. HACS one-click badge front and center. 2. **🚀 5-minute quickstart** — install / first registration (API-key-free safety alert) / verification / next steps in 4 clean steps. 3. **🔑 API key issuance guide** — the headline value. Each service section now contains a clickable "👉 바로 검색" link that lands users directly on the portal's search-results page (data.go.kr / safetydata.go.kr / opinet.co.kr / open.neis.go.kr / data.seoul.go.kr). Each entry shows: - Portal URL - Direct search-results deep link (Korean keywords pre-filled) - Search keyword to type - Operating agency + agency code - Coded endpoint URL (for verification) Three "common mistakes" callout at section top (safetydata.go.kr ≠ data.go.kr / per-dataset 활용신청 / 1-2h activation lag). 4. **⚠️ Known limitations consolidated** — previously scattered per-service warning lines now collected into a single table at one place. Honest public disclosure: scraping fragility, gasapp mobile-app packet capture requirement, AirKorea V4/V5 mismatch, NEIS INFO-200 noise. Two ✅ verified-working badges (pharmacy via live HA query, safety alert via cascading registration test). 5. **Consolidated entity reference table** — friendly names + key attributes across all 13 services in one scannable table. 6. **Compact FAQ** — 10 questions in collapsible form covering all the anticipated objections from new users. 7. **Removed verbose intro sections** — "👋 처음이세요" + recommendation- based reading-order table dropped in favor of letting the linear quickstart drive the reader. .gitignore: also bin throwaway test scripts (`test_*.py`, `*_poll.py`, `pharmacy_READY`) so they don't accumulate in `git status` between sessions. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
공개 직전 README 전면 재작성. 외부 사용자(HACS Default 통해 처음 발견) 첫 인상 + API 키 신청 명확성 최우선.
What changed
Key improvements
1. 🔑 각 API 키마다 "👉 바로 검색" deep link
가장 중요한 변경. 각 서비스마다 클릭 한 번에 해당 포털의 검색 결과 페이지 로 이동하는 링크.
예시:
각 서비스 항목에 명시:
2.⚠️ 자주 발생하는 실수 3가지 callout
🔑 API 키 발급 가이드섹션 상단에 박스로:safetydata.go.kr≠data.go.kr(별도 포털)3. 🚀 5분 만에 시작하기 (linear flow)
4단계 단순화: 설치 → 안전알림 등록 (키 불필요) → 결과 확인 → 더 추가.
4.⚠️ 알려진 한계 한 표로 정리
이전엔 각 서비스 박스에⚠️ 한 줄씩 산재해 외부 사용자에게 "이거 좀 안정적이지 않아 보이네" 인상. 이제 한 표로 모아 정직하게 공개 + 검증된 항목은 ✅ 배지 (약국 + 안전알림).
5. 🎁 Entity 목록 한 표
13개 서비스가 만드는 entity 친화 이름 + 주요 attribute를 한 표에. 사용자가 등록 후 무엇이 만들어지는지 한눈에 확인.
6. 🇬🇧 영어 요약 (collapsible)
Korean expat 거주자도 가치 빠르게 이해할 수 있도록 1단락 영어 hero.
7. 🗑️ Throwaway scripts gitignore
pharmacy_READY,pharmacy_poll.py,test_pharmacy_key.py+ 와일드카드 (test_*.py,*_poll.py) 를 .gitignore에 추가. 이전 세션에서 만든 실험 스크립트들이 매번 `git status`에 보였던 노이즈 제거.Verified facts only
이 README의 모든 endpoint·운영기관 코드는 reference_kr_component_kit_state 메모리의 검증된 사실 (소스 코드에서 추출) + 사용자가 실제 신청 페이지에서 확인한 데이터셋명 (약국·기상특보·단기예보·에어코리아 측정소·에어코리아 대기오염 5건) 기반. 추측 단정 없음.
Test plan
🤖 Generated with Claude Code