문서 작성
TRUSCA 문서는 그것이 설명하는 코드와 함께 출하됩니다 — 사용자 대면 기능은 해당 가이드 페이지가 완성돼야 완료입니다(릴리스 참고). 이 페이지는 그 가이드들의 하우스 스타일입니다: 지금 어떤 종류의 페이지를 쓰고 있는지, 어떻게 제목을 다는지, 스크린샷이나 버전 표기가 언제 필요한지.
페이지마다 토픽 유형 하나
모든 페이지는 한 종류의 질문에 답합니다. 시작하기 전에 어느 쪽인지 정하세요 — 두 유형을 섞은 페이지는 독자가 답을 찾으려 절반을 스크롤해야 하는 가장 흔한 원인입니다. 네 유형은 Diátaxis 프레임워크를 따릅니다.
| 유형 | 답하는 질문 | 형태 | 예시 |
|---|---|---|---|
| 튜토리얼 | "처음 한 번, 처음부터 끝까지 안내해 줄 수 있나요?" | 아무것도 없는 상태에서 동작하는 결과까지 이르는 단일 번호 경로, 중간 확인점 포함. 친근한 어조, 단일 happy path, 분기 없음. | Quickstart |
| 하우투 | "X를 어떻게 하나요?" | 독자가 이미 필요하다고 아는 한 가지 과업의 번호 단계. 전제조건은 앞에, 개념적 곁길 없음. | GitHub Actions |
| 레퍼런스 | "정확한 값, 필드, 상태가 무엇인가요?" | 표와 목록, 스캔 가능, 완결, 서사 없음. 독자는 하나 찾아보고 떠납니다. | 환경변수 |
| 설명 | "왜 이렇게 동작하나요?" | 배경과 근거를 주는 산문. 따라 할 단계 없음. | 분석 유형 |
한 페이지가 정말 두 모드가 필요하면 — 대부분의 user-guide 페이지는 하우투
단계와 레퍼런스 표를 함께 담습니다 — 지배적인 쪽을 앞세우고 다른 쪽은
뒤섞 지 말고 명확히 분리된 섹션에 두세요. 한 섹션이 독립 페이지로 자라면(VEX
섹션이 vulnerabilities.md에서 vex.md로 분리됐듯) 분할하세요.
제목 규칙
- 하우투 제목은 능동 동사 + 명사: "Scan a project", "Upload an SBOM", "Verify SBOM signatures" — "Scanning"이나 "Project scans"가 아닙니다.
- 튜토리얼 제목은 주제로 시작해도 됩니다("Quickstart") — 과업이 아니라 목적지처럼 읽힙니다.
- 레퍼런스·설명 제목은 명사구입니다("환경변수", "분석 유형").
- 섹션 제목은 fragment 앵커입니다. 하나를 개명하면 인바운드 링크가
깨집니다 — 개명해야 한다면 명시적
{#old-anchor}로 기존 앵커를 유지해 기존 링크가 계속 해석되게 하세요.
스크린샷은 제 값을 해야 한다 — 공짜가 아니다
스크린샷은 비쌉니다: UI가 바뀌는 순간 낡고, 스크린 리더에 보이지 않으며, 지역화 표면을 두 배로 늘립니다(모든 KO 페이지가 EN을 미러링). 산문이 담지 못하는 정보를 실을 때만 넣으세요.
스크린샷을 넣는 경우: 페이지가 UI 화면을 안내하고 그림이 모호함을 없앨 때 — 데이터가 채워진 뷰(Vulnerabilities 테이블, 분포 차트), 다중 필드 폼, 레이아웃이 중요한 드로어·다이얼로그. 이런 페이지는 user-guide와 admin-guide 아래에 있습니다.
스크린샷을 넣지 않는 경우:
- 단일 버튼 클릭이나 메뉴 이동 단계 — 텍스트로 서술하세요("Scan 클릭"). 버튼 사진은 노이즈입니다.
- 사실상 명령이나 설정 파일인 것 — 설치, CI 연동, 그리고 레퍼런스 서가 대부분은 CLI·YAML이고, 코드펜스가 정확하고 복사 가능하며 diff되는 산출물입니다. 터미널 스크린샷은 엄밀히 더 나쁩니다.
- 메시지 텍스트, 빈 상태, 에러 문구 — 검색·번역되도록 텍스트로 인용하세요.
그래서 installation/, ci-integration/, reference/에 스크린샷이 없는
것이며, 이는 공백이 아니라 옳습니다. 넣을 때는 손으로 캡처한 스크린샷을
붙이지 말고 자동 파이프라인(make screenshots-capture, 테스트
가이드 참고)으로 캡처해, 일관된 1440×900으로 재생성되고
크기 게이트를 통과하게 하세요.
기능이 언제 들어왔는지 표기
사용자 대면 기능은 섹션 제목 바로 아래에 한 줄짜리 버전 표기를 넣어, 독자가 자기 배 포에 무엇이 있는지 알 수 있게 하세요.
### Group by upgrade — the remediation worklist
*Introduced in v0.17.0.*
...
이는 버전별 문서 스냅샷(Docusaurus가 소규모 사이트에는 권하지 않는)의 가벼운 대안입니다. 새 기능 섹션이 출하될 때 붙이세요 — 기존 트리 전체에 소급할 필요는 없습니다. 릴리스 노트가 버전별 전체 체인지로그로 남고, 이 표기는 가이드를 읽는 독자가 필요로 하는 "언제부터"를 그 자리에서 알려줄 뿐입니다.
두 언어를 함께
docs-site/docs/** 아래 모든 페이지는 docs-site/i18n/ko/.../current/**에
한국어 미러가 있습니다. 같은 PR에서 함께 바꾸세요 — EN 원본보다 뒤처진 KO
페이지는 드리프트입니다. 한국어 페이지는 추가로 번역투 린터(node tools/ko-style/lint.mjs --changed --fail-on S2)를 통과해야 합니다.
ko-style README
참고.