위키 원칙과 철학¶

이 문서는 Swiftlang wiki를 어떤 종류의 위키로 만들 것인지에 대한 기준 문서다. 단순한 운영 메모가 아니라, 이 위키의 단단한 규칙과 앞으로도 발전할 철학을 함께 적는다.

핵심 전제는 하나다.

이 위키는 - 작업 일지 - 개인 메모장 - 링크 창고 - 문서 덤프 가 아니라,

Swift와 Swift Compiler를 이해하기 위한 지식베이스다.

이 문서의 역할¶

이 문서는 두 층으로 읽는다.

단단한 규칙
웬만하면 예외를 두지 않고 지켜야 하는 기준
문서 작성, 편집, 확장, 연결 방식의 기본 규칙
발전하는 철학
위키가 어떤 방향으로 진화해야 하는지에 대한 장기 원칙
필요하면 수정될 수 있지만, 수정은 명시적으로 이 문서와 연대기에 반영한다

1. 단단한 규칙¶

1. 주제 페이지는 주제 자체를 설명해야 한다¶

subject page는 "왜 이 페이지를 만들었는가"보다 "이 주제가 무엇인가"를 설명해야 한다.

좋은 예: - 개념 정의 - 설계 동기 - 구현 구조 - 현재 의미와 읽는 방법

피해야 할 것: - 기존 위키에 뭐가 없었다는 내부 사정 - 이번 배치에서 왜 추가했는지 같은 제작 맥락 - 위키 운영자/작성자 중심 서술

즉 subject page의 주인공은 항상 위키가 아니라 주제다.

2. 위키 메타 정보는 메타 페이지로 분리한다¶

위키 내부 발전사, 편집 방향, 배치 기록, 운영 규칙은 subject page에 흩뿌리지 않는다.

대신 전용 메타 페이지로 보낸다. - 위키 확장 연대기 → 위키 지식 연대기 - 작업 로그 → log.md - 원칙/철학 → 이 문서 - 실제 편집 체크 → 위키 편집 체크리스트 - 실제 페이지 뼈대 → 위키 생성 템플릿 - frontmatter/taxonomy 기준 → 위키 taxonomy / frontmatter 규칙

즉 지식과 위키 운영은 연결되지만, 같은 페이지 안에서 섞이지는 않는다.

3. 새 페이지는 반드시 그래프 안에 들어와야 한다¶

새 페이지는 단독 문서로 끝나면 안 된다. 만들었다면 반드시 위키 그래프 안에 연결돼야 한다.

최소 기준: - nav에 들어갈 것 - 관련 허브에서 발견될 것 - keyword-network 또는 관련 키워드 축에서 찾을 수 있을 것 - 역링크를 몇 군데 받을 것 - 추천 읽기 순서나 같이 보면 좋은 페이지가 있을 것

즉 페이지 수보다 연결성이 더 중요하다.

4. 허브 페이지는 1급 문서다¶

이 위키는 세부 문서만 많이 쌓는 방식으로 가지 않는다. 허브 페이지를 적극적으로 만든다.

허브의 역할: - 큰 그림 제공 - 세부 페이지 사이 관계 설명 - 입문 경로 제공 - 설계 축/구현 축/ABI 축을 다시 묶기

즉 허브는 요약본이 아니라, 독자의 사고 경로를 설계하는 문서다.

5. 역사 문서는 현재 문맥과 함께 읽게 만든다¶

proposal, manifesto, archive, rejected 문서는 그 자체로 끝내지 않는다.

반드시 밝혀야 하는 것: - 당시 어떤 문제를 풀려 했는가 - 지금 무엇이 남았고 무엇이 사라졌는가 - 현재 어떤 구현/개념 페이지와 이어서 읽어야 하는가

즉 역사 문서는 박물관 자료가 아니라, 현재 구현을 이해하는 렌즈로 다룬다.

6. 정확성은 과장보다 우선한다¶

이 위키는 설명력이 중요하지만, 설명을 위해 사실을 과장하면 안 된다.

특히 조심할 것: - proposal의 문법/속성이 현재도 그대로라고 암시하지 않기 - 구현 세부가 1:1로 이어진다고 단정하지 않기 - "항상" "완전히" 같은 표현 남용하지 않기 - 개념적 유사성과 실제 채택을 구분하기

좋은 문장은 강한 주장보다 정확한 경계선을 가진 문장이다.

7. 품질 검증은 문서 작성의 일부다¶

이 위키에서 문서 작성은 텍스트 입력으로 끝나지 않는다. 다음이 모두 문서 작업의 일부다. - nav 반영 - 링크 정리 - page count / crossref count 동기화 - build - doctor - 테스트 - clean status 확인

즉 publish 가능 상태까지 가야 문서가 끝난다.

8. 관련 변경은 한 배치로 묶는다¶

가능하면 단일 페이지만 뜯어 고치지 않는다. 관련된 변경을 한 번에 묶는다.

예: - 새 crosswalk 페이지 작성 - 허브 갱신 - keyword-network 갱신 - chronology 갱신 - reverse link 추가 - 검증 및 push

이렇게 해야 위키가 중간 상태에서 오래 머무르지 않는다.

2. 발전하는 철학¶

1. 이 위키는 문서 저장소보다 지식 그래프에 가깝다¶

문서가 많다고 좋은 위키가 아니다. 좋은 위키는 - 개념이 연결되고 - 읽기 경로가 있고 - 다른 페이지로 자연스럽게 이동되며 - 독자가 큰 그림과 세부를 오갈 수 있다.

즉 이 위키는 선형 책보다 탐색 가능한 그래프를 지향한다.

2. 비정형 지식에서 구조화 지식으로 점진적으로 나아간다¶

처음부터 모든 것을 엄격한 스키마에 넣지는 않는다. 하지만 가능하면 점점 더 구조화한다.

예: - 허브와 세부 페이지 구분 - proposal → implementation 읽기 경로 - keyword-network - 분류/태그/aliases 정리 - 페이지 유형 구분 (summary, concept, entity, reference, meta)

즉 이 위키는 자유 텍스트에서 출발해도, 시간이 갈수록 구조가 더 잘 드러나야 한다.

3. 읽는 사람의 사고 순서를 설계한다¶

좋은 페이지는 정보만 주는 것이 아니라 어디서 들어오고 어디로 가야 하는지도 보여 준다.

그래서 이 위키는 - 빠른 탐색 - 추천 읽기 순서 - 같이 보면 좋은 페이지 - 허브 페이지 - 교차 읽기 페이지 를 중요하게 다룬다.

즉 설명은 내용만이 아니라 독자의 다음 이동까지 포함한다.

4. 전문성을 유지하되 입구를 닫지 않는다¶

Swift compiler 주제는 어렵다. 그래도 위키는 전문성을 이유로 입문 경로를 포기하지 않는다.

지향점: - 입문 허브가 있다 - 용어 사전이 있다 - 공식 문서와 구현 문서를 이어 준다 - 큰 그림 허브와 세부 문서가 함께 있다

즉 깊이는 유지하되, 독자가 들어오는 문턱은 낮춘다.

5. 운영 원칙도 공개 지식이 될 수 있다¶

이 위키는 subject page에서 메타를 분리한다. 하지만 메타를 숨기지는 않는다.

대신 별도 페이지에 공개한다. - 어떤 철학으로 쓰는지 - 어떻게 확장되는지 - 어떤 방식으로 품질을 관리하는지

이건 위키 자체의 투명성과 지속가능성을 높인다.

6. 반복 가능한 좋은 작업은 구조로 승격한다¶

한 번 잘 된 작업은 다음에도 재현 가능해야 한다. 그래서 반복 패턴은 - 스킬 - 체크리스트 - 원칙 문서 - chronology 로 승격한다.

즉 이 위키는 페이지뿐 아니라 위키를 키우는 방법 자체도 구조화한다.

3. 이 위키에서 페이지를 어디에 둘 것인가¶

subject page¶

주제 자체를 설명하는 페이지. 예: - Swift 타입 시스템 - Swift 런타임 - ABI: 타입 레이아웃

crosswalk page¶

과거 문서와 현재 구현을 연결하는 페이지. 예: - Value Semantics / COW proposals → ownership/runtime 교차 읽기 - Enums / EnumStyle proposals → 타입 시스템 / API 표면 / 레이아웃 교차 읽기

hub page¶

여러 세부 페이지를 하나의 큰 그림으로 묶는 페이지. 예: - Swift 전체 지도 - Swift 소유권·메모리 모델

meta page¶

위키 운영 원칙, 연대기, 메타 구조를 다루는 페이지. 예: - 위키 지식 연대기 - 이 문서

4. 편집 체크리스트¶

새 페이지를 만들거나 크게 고칠 때는 최소한 이 질문을 본다.

상세판은 위키 편집 체크리스트를 기준으로 쓴다.

이 페이지는 주제를 직접 설명하는가?
위키 내부 사정/작업 히스토리가 subject page 안에 섞여 있지는 않은가?
관련 허브/역링크/키워드 축에 연결됐는가?
독자가 다음에 어디로 가야 할지 보이는가?
현재 구현과 역사 문서의 경계가 명확한가?
이 페이지는 위키 그래프 전체를 더 강하게 만드는가?

5. 이 문서를 어떻게 업데이트할 것인가¶

이 문서는 고정된 선언문이면서도, 완전히 닫힌 문서는 아니다.

업데이트 원칙: - 자주 바꾸지 않는다 - 바꿀 때는 문장 하나의 수정보다 방향의 변화가 있을 때 바꾼다 - 바뀐 경우 위키 지식 연대기과 log.md에 남긴다 - 앞으로의 작업 스킬/체크리스트도 가능하면 같이 맞춘다

즉 이 문서는 즉흥적 메모가 아니라, 위키의 장기적인 기준선이다.