이 페이지들을 쓰는 방식

우리가 염두에 두는 독자는 사이트를 한 번도 본 적이 없습니다. 우리의 용어도, 페이지 이름도, 어느 블록이 중요한지도 모릅니다. 아래의 모든 내용은 여기서 출발합니다.

1. 한 페이지, 한 가지 역할

페이지는 다섯 종류이며, 한 페이지는 정확히 하나를 고릅니다.

하위 시스템을 설명하기 시작한 빠른 시작 페이지는 URL 하나에 페이지 두 개가 들어 있는 셈입니다. 나누십시오. 무거운 주제는 별도의 방법 안내 페이지로 옮기고, 빠른 시작에는 그곳을 가리키는 짧은 단계 하나만 남깁니다.

2. 첫 문장은 약속이고, 제목들이 그 약속을 지킵니다

모든 페이지는 독자가 무엇을 할 수 있게 되거나 이해하게 되는지를 말하는 이탤릭 문장 하나로 시작합니다. 이어지는 섹션은 정확히 그것을, 그 순서대로 전달합니다. 약속의 어느 부분에도 기여하지 않는 섹션이 있다면 약속이 너무 좁거나 그 섹션이 다른 페이지에 속하는 것입니다.

3. 원리보다 결과를 먼저

화면, 답, 수치 같은 결과물을 먼저 보여 주고 그것이 어떻게 만들어지는지는 나중에 설명합니다. 사이트를 보지 못한 독자는 아직 보지 않은 것에 대한 설명을 머릿속에 담아 둘 수 없습니다.

4. 제목은 우리의 명사가 아니라 독자의 작업입니다

“특정 결제 찾기”이지 “정산 테이블 컴포넌트”가 아닙니다. 페이지를 훑는 독자는 우리의 구조가 아니라 자신의 질문을 찾고 있습니다.

5. 컨트롤에 대해 경고하지 말고 선택을 가르치십시오

동작이 누군가를 놀라게 할 수 있을 때는 그렇게 만드는 속성과 그에 대한 대처법을 설명합니다. “블록 번호는 고유하지 않습니다. 모든 네트워크에 같은 번호가 있으므로 먼저 네트워크를 바꾸거나 다른 곳에서 다시 검색하십시오”는 가르침이고, “조심하세요, 블록 검색은 오해를 부릅니다”는 그렇지 않습니다. 단순한 경고는 독자가 스테이블코인을 잃을 수 있는 경우에만 쓰고, 이를 막는 행동과 함께 제시합니다.

6. 세 가지 답을 구분해 이름 붙이십시오

이 제품은 없음(확인했고 아무것도 찾지 못함), 이름이 붙은 결과, 알 수 없음 / 평가 안 됨(확인할 수 없었음)을 구분합니다. 이 중 하나를 보여 주는 페이지는 세 가지를 모두 분리해 유지해야 하며, 알 수 없음이 깨끗함으로 읽히게 해서는 절대 안 됩니다. 이것이 사이트의 핵심 약속이며, 가이드가 가장 흐리기 쉬운 부분입니다.

7. 페이지가 스스로 설명하는 것을 베끼지 마십시오

제품 화면에 자체 설명이 있으면 그곳으로 링크하고 언제 열어 보면 되는지를 설명합니다. 설명이 두 벌이면 그중 하나는 이미 틀렸다는 뜻이며, 대개 가이드에 있는 쪽이 오래된 것입니다.

8. 모든 주장은 배포된 사이트에서 확인합니다

페이로드만으로도, 소스만으로도, 이전 초안만으로도 아닙니다. 확인할 수 없다면 쓰지 마십시오. 임계값과 수치는 그것을 만든 근거(10×, 180 days, 50 to a page)와 함께 인용해 다음 독자가 다시 확인할 수 있게 합니다.

가장 많은 것을 찾아내는 작업 방식은 세 번의 검토와 하나의 대조입니다. 페이지를 화면과 글자 그대로 대조해 읽고, 다른 진입점으로 다시 들어오고, 경계 상황(빈 주소, 잘못된 네트워크, 실패한 조회)을 시도한 다음, 놀라웠던 것은 무엇이든 적기 전에 다시 확인합니다.

자리를 잡은 네 가지 습관이 있습니다. 각각 그것 없이 가이드가 무언가를 틀린 뒤에 생겼습니다.

• 컨트롤은 읽지만 말고 눌러 보십시오. 비활성 상태와 툴팁은 독자를 위해 쓰인 것이며 다른 어디에도 없습니다. “no sub-$1 counterparties in this kept set — nothing to hide”, “deterministic report layout” 같은 것입니다. 또한 어떤 페이저는 테이블을 넘기고 다른 페이저는 테이블을 늘린다는 사실도 클릭해 봐야만 알 수 있습니다.
• 대상 하나가 아니라 서로 다른 넷을 열어 보십시오. 활발한 지갑, 컨트랙트, 거래소, 솔라나(Solana) 계정은 각각 다른 대상에서 보이는 블록을 숨깁니다. 지금까지 발견된 모든 잘못된 서술은 예시 하나로만 확인한 페이지에서 나왔습니다.
• 언급하는 화면이 아직 존재하는지 확인하십시오. 가이드 두 개가 이미 삭제된 것으로 독자를 보냈습니다. 페이지를 열어 보기만 했어도 두 주장 모두 살아남을 수 없었습니다.
• 화면의 이름은 API의 이름이 아닙니다. 클래스는 unknown이지만 표시는 not assessed라고 쓰여 있고, 배지는 분류이지 CONTRACT라는 단어가 아닙니다. 독자가 보는 것을 쓰십시오.

여기서 색은 의미를 담고 있으며, 그럴 때는 본문에도 써야 합니다. OFAC 배너는 주소가 목록에 올라 있으면 빨간색이고, 온체인 달러의 이력만 목록에 닿아 있으면 주황색입니다.

9. 날짜는 쓰인 그대로의 의미입니다

헤더의 verified 날짜는 누군가 마지막으로 페이지를 제품과 대조해 확인한 날이지, 텍스트를 수정한 날이 아닙니다. 첫 문장에도 같은 날짜가 들어가며, 일부만 다시 읽었다면 어느 부분인지 밝힙니다. 두 날짜가 서로 다른 파일은 독자에게 쓸모 있는 정보를 아무것도 주지 않습니다.

10. 한계 목록은 항목이 늘기도 하고 줄기도 합니다

“알려진 한계” 섹션은 살아 있는 목록입니다. 제품이 무언가를 고치면 그 항목은 빠지고, 절반만 고쳐졌다면 여전히 사실인 절반으로 좁혀집니다. 단서만 계속 쌓아 가는 가이드는 결국 더 이상 존재하지 않는 제품을 설명하게 됩니다.

11. 독자에게 먼저 필요한 것과 이 페이지가 다루지 않는 것을 말하십시오

페이지가 무언가를 전제한다면(주소가 본인 것이라거나, 어떤 네트워크를 뜻하는지 안다거나) 독자가 중간쯤에서 알게 두지 말고 맨 위에 말하고 그것을 얻을 수 있는 곳으로 링크하십시오. 이웃한 질문이 범위 밖이라면 그것을 밝히고 그 주제를 맡은 페이지를 가리키십시오. 끝까지 읽고도 여전히 답을 찾고 있는 독자는 처음부터 실패한 것입니다.

12. 독자가 처한 상황을 이름 붙이고, 보이는 문구를 인용하십시오

독자가 마주쳐도 해석할 수 없는 것(빈 테이블, 대시, not assessed, no data)에 대해서는 메커니즘이 아니라 상황을 기준으로 섹션을 쓰고, 제품의 문구를 화면에 나타나는 그대로 정확히 인용합니다.

블록을 열었더니 TRANSFERS 아래에 0, BLOCK TIME에 대시, 테이블에 no data가 표시됩니다 — 이 번호는 이 네트워크에서 유효하지만 해당 블록에 대해 보관된 스테이블코인 전송이 없습니다. 블록이 사이트가 보관하는 원시 행보다 오래되었거나, 다른 네트워크의 블록이거나, 조용한 블록이었습니다. 네트워크를 바꿔 다시 검색하십시오.

그대로 인용하면 독자는 화면에 보이는 것을 페이지와 맞춰 볼 수 있고, 그 문구로 검색할 수도 있습니다. 바꿔 말하면 두 가지가 모두 깨집니다.

화면에 표시되는 그대로의 규칙 12 모범 예시. — stablescan.achivx.com 스크린샷, 2026-10-10; 다크 테마 캡처는 2026-10-11.

13. 상태를 설명할 때는 모든 형태를 나열하십시오

칩, 타일, 카드가 여러 방식으로 표시될 수 있다면 그 방식을 세어 모두 제시하십시오. 네 가지 중 세 가지만 나열한 가이드는 아무것도 나열하지 않은 가이드보다 나쁩니다. 빠진 하나가 바로 독자가 해석할 수 없는 상태이기 때문입니다. not indexed on this network라고 표시된 솔라나 동결 칩은 clear의 네 번째 변형이 아닙니다. 때때로 아예 나타나지 않는 블록도 마찬가지입니다. 언제, 왜 그런지 말하십시오.

13a. 가이드는 일반적인 경로를 담고, 전체 목록은 참고 문서로 보냅니다

규칙 13은 상태의 모든 형태를 요구하며, 그럴 만한 이유가 있었습니다. 하지만 그것을 어디에 나열하느냐도 그만큼 중요합니다. 가이드는 작업 도중인 사람이 읽고, 목록은 필요할 때 찾아봅니다. 따라서 다음과 같습니다.

• 가이드에는: 일반적인 경우와, 잘못 읽으면 독자가 무언가를 잃는 형태를 씁니다. not indexed on this network는 이상 없음이 아니고, revoked는 아무 일도 일어나지 않았다는 뜻입니다. 두세 가지를 문장으로 씁니다.
• reference/에는: 전체 목록을 알파벳순이나 표로 정리해 둡니다. 모든 형태가 필요한 사람은 그곳을 찾아봅니다. 용어집은 어휘를, 한도는 숫자를 맡습니다.

오류는 그것이 발생하는 단계에서 한 줄로 이름 붙이고 나머지는 한곳으로 보내십시오. Claude 설치 가이드가 “'irm' is not recognized가 보이면 PowerShell이 아니라 CMD에 있는 것입니다”라고 말하고 전체 목록은 문제 해결 페이지로 보내는 것처럼 말입니다.

징후: 대부분이 문자열 표와 겹겹이 쌓인 인용 블록으로 이루어진 페이지는 가이드이기를 멈추고 명세서가 된 것입니다. 세어 보십시오. 화면 하나를 쓰기 위해 독자가 다섯 줄짜리 표를 머리에 담아야 한다면, 그 화면의 중요한 세 가지 상태는 문장으로, 나머지 둘은 용어집으로 가야 합니다.

14. 한 주제는 한 페이지가 맡고, 다른 페이지는 그곳을 가리킵니다

두 페이지가 같은 설명을 담을 수 있다면 한 페이지가 그것을 맡고 그렇다고 밝히며, 나머지는 클릭할 이유와 함께 링크합니다. 어느 쪽이 살아 있는 페이지인지 “거기서 시작하십시오”처럼 밝혀 두어, 다음 작성자가 갈라서 새로 쓰지 않고 이어서 확장하게 하십시오.

15. 다음에 갈 곳으로 마무리하십시오

링크 두세 개에서 네 개, 각각 클릭할 이유와 함께 제시합니다. 대부분의 독자에게 필요한 것을 골라 맨 앞에 두십시오.

16. 사용자에게 보이는 변경은 가이드 업데이트와 함께 배포합니다

엔지니어링 규칙이 여기에도 적용됩니다. 변경이 사용자가 보거나 할 수 있는 것을 바꾼다면, 영향을 받는 페이지도 같은 머지 리퀘스트에서 바뀌어야 하며 한계 섹션도 포함됩니다. 제품보다 뒤처진 가이드는 목차가 달린 거짓말입니다.

페이지의 형태

<!-- doc: status=current | verified=YYYY-MM-DD -->
# Title — the reader's words, not ours

*One sentence: what you will be able to do or understand.* — Updated YYYY-MM-DD (what
was checked, and against what).

## Before you start                                ← only if the page assumes something
## What this is / What you can find out here       ← intro pages and hubs
## 1..N task sections, each ending in a result     ← quickstart and how-to
## If you see …                                    ← situations, quoted verbatim, with the fix
## Known limitations                               ← what it cannot do, and the way round
## Where to go next                                ← 2–4 links with reasons

이 규칙들은 어디서 왔는가

출처는 두 가지이며, 페이지가 어딘가 잘못되었다고 느껴질 때 둘 다 다시 읽어 볼 만합니다. 첫째는 이 제품 자체입니다. 위의 모든 규칙은 이곳에서 누군가를 오도한 페이지 때문에 생겼습니다. 둘째는 Claude 플랫폼 문서로, 같은 문제들에 대해 유난히 엄격합니다. 한 화면에 들어가고 다음으로 안내하는 빠른 시작, 한 문장의 약속에 정확히 그 섹션들로 답하는 허브 페이지, 이론보다 먼저 나오는 작동하는 예제, 증상을 먼저 쓰고 메시지를 독자가 보게 될 그대로 인용하는 오류 참고 문서, 무엇을 전제하고 무엇을 해결하지 않는지 밝히며 시작하는 페이지가 그렇습니다.

2026-10-10 업데이트(규칙 13a는 2026-10-01 추가, 규칙 12의 모범 예시는 화면에서 다시 캡처, 이 규칙들은 2026-10-05..10에 25개 페이지 전체에 적용).