본문으로 건너뛰기
series develop design frontend backend infra devops ai user-manual design-doc security appendix

본 시리즈 바깥의 인접 문서들 - 개발자를 위한 기술문서 입문 ep.09

이 시리즈는 내부 개발 협업에서 쓰는 문서에 초점을 맞췄습니다. README부터 PR까지, 동료 개발자와 운영자가 독자였습니다.

그러나 그 바깥에도 자리한 문서들이 있습니다. 외부 사용자를 위한 글, 결정 직전에 동료에게 의견을 구하는 글, 공격자까지 독자에 포함된 글. 본 시리즈가 직접 다루지 않은 세 문서를 가볍게 짚으며 마칩니다.

세 문서의 자리

먼저 셋의 위치를 한 장에 정리합니다.

본 시리즈 바깥의 세 인접 문서 비교 다이어그램. 상단 안내: 본 시리즈는 내부 개발 협업의 글에 집중했습니다 — 이 셋은 그 바깥에 자리한 문서들입니다. 세 컬럼이 나란히 비교된다. 첫째 USER MANUAL 사용자 매뉴얼(파란 원 아이콘): 독자는 비개발자 최종 사용자, 분면은 How-to의 확장, 표현은 전문용어 최소화·UI 라벨 사용과 스크린샷·GIF 필수, 유지비용은 매우 높음(UI 바뀌면). 둘째 DESIGN DOC 디자인 문서(황토색 사각형 아이콘): 독자는 동료 엔지니어, 분면은 Explanation의 일종이며 결정 직전의 글, RFC와의 차이는 더 좁은 범위이고 팀 내 합의용, 수명은 구현 후 역할 종료이며 필요 시 ADR로 박제. 셋째 SECURITY DOC 보안 문서(적색 삼각형 아이콘): 독자는 내부 개발자·SRE와 외부 보안 연구자, 분면은 Reference + Explanation, 하위 종류는 Threat Model, 보안 가이드라인, Disclosure Policy, 핵심 긴장은 공개할 것과 공개 안 할 것의 경계.

세 문서가 본 시리즈의 다른 글들과 다른 결정적 차이는 독자가 시스템 바깥에 있다는 점입니다. 그 차이가 톤·언어·시각 자료의 비중을 크게 바꿉니다.

사용자 매뉴얼

소프트웨어를 만들면 사용자가 옵니다. 그 사용자 중 다수는 개발자가 아닙니다. 마케터, 회계, 의사, 교사, 학생. 이들에게 보낼 글은 튜토리얼과 하우투의 친척이지만, 어휘가 다릅니다.

사용자 매뉴얼의 핵심 차이

  1. UI 라벨로 지칭한다.
    비개발자는 함수명·필드명을 모릅니다. 화면에 보이는 그대로의 라벨로 지칭해야 합니다. 아래에서 후자는 비개발자가 그대로 따라갈 수 있습니다. 전자는 누군가의 통역이 필요합니다.
약한 매뉴얼:
> userPreferences API의 notification_enabled 필드를 true로 설정합니다.

강한 매뉴얼:
> [설정 > 알림] 화면에서 [이메일 알림 받기] 스위치를 켜세요.

  1. 스크린샷이 본문이다.
    비개발자 매뉴얼에서 스크린샷은 보조가 아니라 본문입니다. 글이 스크린샷을 따라가고, 스크린샷 안에 화살표·번호가 들어갑니다. GIF는 짧고 자주 쓰는 액션에 강합니다. 드래그앤드롭, 팝업 열기처럼 정적 스크린샷으로 못 잡는 것.

  2. 사용자의 목적으로 글을 묶는다.
    개발자 문서는 기능 단위(/api/charge)로 묶기 쉽지만, 사용자 매뉴얼은 시나리오 단위로 묶어야 합니다. 아래에서 후자는 사용자가 떠올리는 질문 그대로입니다. 전자는 작성자의 머릿속입니다.

약한 분류:
- 결제
- 알림
- 사용자
- 설정

강한 분류:
- 처음 시작하기
- 첫 결제 받기
- 알림 설정하기
- 팀 멤버 초대하기
- 결제 환불하기

사용자 매뉴얼이 자주 무너지는 지점

  1. 개발자가 쓴 티가 난다.
    ”API”, “request”, “response”, “JSON” 같은 단어가 등장하면 비개발자는 페이지를 닫습니다.
  2. UI가 바뀌었는데 문서는 그대로다.
    가장 흔한 실패입니다. 스크린샷이 지금 화면과 다른 매뉴얼은 없는 것보다 나쁩니다. 비개발자는 자기가 잘못한 줄 압니다. 정기적인 문서-UI 정합성 점검이 필요합니다.
  3. 문제 해결 가이드가 없다.
    ”이 기능이 안 보여요”는 사용자에게서 가장 자주 오는 질문입니다. 매뉴얼에 흔한 문제 섹션이 있으면 지원 비용이 크게 줄어듭니다.
  4. 다국어 정합성이 깨진다.
    한국어 매뉴얼과 영어 매뉴얼이 내용이 다르면 어느 게 진실인지 사용자가 알 수 없습니다. 원본을 하나로 유지하고 번역하는 흐름을 권장합니다.

도구

여러 도구가 있지만 가벼운 접근부터 권장합니다.

  • 마크다운 기반 사이트: Docusaurus, MkDocs, GitBook, Mintlify. 개발자가 익숙한 흐름으로 매뉴얼을 만들 수 있습니다.
  • 이미지 캡처 자동화: Playwright + 스크립트로 UI 변경 시 자동으로 스크린샷 갱신.
  • In-app 가이드: Intro.js, Userpilot, Pendo. 문서 밖에서 사용자를 인도.

문서와 in-app 가이드는 상호 보완입니다. 둘 다 필요할 때가 많습니다.

공개 도움말 센터가 매뉴얼을 다루는 방식

대중 소프트웨어의 공개 도움말 센터를 두어 곳 들여다보면 위의 원칙이 어떻게 구현되는지 또렷해집니다.

  • Notion Help: 좌측 사이드바는 페이지와 블록 · 데이터베이스 · 공유 및 협업 · Notion AI · 자동화 및 연결처럼 기능 단위 카탈로그이지만, 맨 앞에 시나리오 항목인 시작하기가 놓여 처음 온 사용자의 첫 클릭을 가져갑니다. 거기에 더해 홈 화면에는 Notion 101 · 데이터베이스 · 댓글과 리마인더 같은 시나리오 카드와 Project management · Engineering · Design · Marketing · Startup · Enterprise 같은 역할 기반 “팀별로 둘러보기” 섹션이 별도로 자리합니다. 한 도움말 센터 안에 기능 색인 + 시나리오 입구 + 역할 입구가 겹쳐 있는 형태입니다.

    Notion 도움말 센터 홈 화면 스크린샷. 좌측에 13개의 기능 카테고리 사이드바(시작하기, 워크스페이스 및 설정, 페이지와 블록, 데이터베이스, 공유 및 협업, 자동화 및 연결, Notion AI, 관리와 보안, 메일·캘린더 및 앱, 마켓플레이스 및 템플릿, 요금제와 청구, 문제 해결 방법, 개발자 플랫폼)가 있고 맨 앞은 시나리오 항목인 시작하기. 우측 메인 영역에 안녕하세요 무엇을 도와드릴까요 검색창과 그 아래 인기 주제 섹션의 카드 6개(Notion 101, Notion AI 사용, 댓글과 리마인더, 데이터베이스, 이미지·파일·미디어, 멤버 vs 게스트)가 격자로 배치되어 있다.

  • Slack Help Center: 단계가 UI에 보이는 라벨 그대로 입니다. — “사이드바에서 ＋ 더하기 기호를 클릭”, “채널 이름을 입력하고 공개 또는 비공개 여부를 선택한 다음 새로 만들기를 클릭”. 함수명도, 내부 자원명도 본문에 들어오지 않습니다. 거기에 본문 상단엔 동작을 그대로 보여주는 GIF가 한 장 박혀 글의 머리를 움직이는 화면이 잡습니다. 앞서 짚은 UI 라벨로 지칭한다와 스크린샷이 본문이다 두 원칙이 한 글 안에서 같이 작동하는 사례입니다.

    Slack 도움말 글 "채널 만들기" 본문 스크린샷. 상단엔 Slack 데스크톱 앱에서 사이드바의 ＋ 추가 아이콘 위에 커서가 올라가는 GIF가 한 장 박혀 있다. 그 아래에 "채널 만들기" 제목과 데스크톱·모바일 환경 전환 탭, 그리고 1·2·3 번호가 매겨진 단계가 UI 라벨 그대로 적힌다. 1. 사이드바에서 ＋ 더하기 기호를 클릭합니다. 2. 채널을 선택합니다 — 유료 플랜인 경우 빈 채널을 선택해 일반 채널을 만들거나 템플릿을 선택해 특정 목적에 맞게 자동 설정할 수 있다. 3. 채널 이름을 입력하고 공개 또는 비공개 여부를 선택한 다음 새로 만들기를 클릭합니다. 그 아래엔 멀티 채널 게스트에 대한 참고 박스가 이어진다.

  • 1Password Support: 허브 카드를 Get started · Team members: Get started · Using 1Password · Families · Businesses · MSP · Developers · Get help · Security처럼 독자 그룹·시나리오 단위로 자르고, 그 아래에 Mac · iOS · Windows · Android · Linux · ChromeOS · Command Line 플랫폼 그리드를 별도로 둡니다. 무엇을 하려고 왔는가(시나리오)와 어디서 쓰는가(플랫폼) 두 축으로 입구가 갈라져, 사용자가 떠올린 질문에 맞춰 진입할 수 있습니다.

    1Password Support 허브 페이지 스크린샷. 두 행에 걸쳐 9개의 큰 카드가 격자로 배치되어 있다. 첫 행은 Get started 카드(Set up 1Password for yourself or your family — Get started 버튼)와 Team members: Get started 카드(Set up 1Password at your workplace — Join your team 버튼). 둘째 행은 Using 1Password · Families · Billing and subscriptions, 셋째 행은 Businesses · Managed Service Providers · Developers, 마지막 행은 Get help · Security. 각 카드는 독자 그룹 또는 시나리오 단위로 갈라져 있고, 본문 더 아래엔 별도의 Mac·iOS·Windows·Android·Linux·ChromeOS·Command Line 플랫폼 그리드가 이어진다.

세 곳의 공통점은 글 하나하나가 짧고, 진입 경로가 여러 갈래로 준비된다는 것입니다. 100페이지짜리 PDF 매뉴얼이 아닙니다. 각 글이 5분짜리 한 시나리오를 끝까지 책임지고, 그 외 영역은 옆 글이 책임지며, 기능 색인 / 시나리오 / 역할 / 플랫폼 가운데 사용자가 떠올린 축으로 들어올 수 있도록 입구가 여러 개 마련됩니다.

다국어 매뉴얼 운용

한국어·영어 매뉴얼을 둘 다 운영해야 할 때 자주 쓰는 두 가지 흐름이 있습니다.

  • 단일 원본 + 번역: 영어(또는 한국어) 한 쪽을 진짜가 있는 원본으로 정하고, 하나는 번역으로써 따라갑니다. Crowdin, Lokalise, Phrase 같은 도구가 번역 워크플로를 관리합니다. 원본이 갱신되면 번역에 outdated 플래그가 자동으로 붙어 번역가에게 작업이 큐로 들어갑니다. 정합성을 가장 안전하게 유지하지만, 지역별 차이(법·결제 통화·UI 라벨 차이)를 반영하기 어렵습니다.
  • 지역별 독립 운영: 각 언어 매뉴얼이 별도 저장소·별도 작성팀을 가집니다. 지역별 특수성을 반영하기 좋지만, 같은 기능이 두 매뉴얼에서 다르게 적힐 위험이 큽니다. 대형 SaaS의 한국 법인이 일부 채택하는 형태입니다.

대부분의 팀에 단일 원본 + 번역이 낫습니다. 지역별 독립은 콘텐츠 자체가 지역마다 다른 도메인(금융·세무·헬스케어 등)에서나 드는 비용이 합리적입니다.

디자인 문서

디자인 문서(Design Doc) 는 구현 직전에 동료에게 의견을 구하는 글입니다. RFC와 자주 헷갈리지만, 보통 다음 점에서 다릅니다.

  • 범위: RFC가 조직 차원의 결정이라면, 디자인 문서는 팀 차원 또는 기능 차원의 결정입니다.
  • 수명: RFC는 한 번 Accepted되면 ADR로 박제됩니다. 디자인 문서는 구현이 끝나면 역할 종료입니다.
  • 길이: RFC가 길어지는 경우가 많다면, 디자인 문서는 5~10페이지가 흔합니다.

Google이 내부적으로 광범위하게 쓰는 Design Doc 문화가 대표적입니다. 큰 기능을 시작하기 전 반드시 1~2주를 디자인 문서에 투자합니다. 문화 전반은 Design Docs at Google에서 잘 정리되어 있고, 채워진 실제 예시는 OSS 생태계에서 찾을 수 있습니다 — Kubernetes KEP-753 (Sidecar Containers)는 Summary · Motivation · Goals · Non-Goals · Proposal · Design Details · Alternatives · Risks · Test Plan이 모두 채워진 큰 사례, Chromium의 about:conflicts 디자인 문서는 같은 골격을 작은 기능에 맞게 줄인 가벼운 예시입니다.

디자인 문서의 표준 구조

# Design: [기능 이름]

**Author**: [이름]
**Status**: Draft | In Review | Approved
**Reviewers**: [이름들]
**Last Updated**: YYYY-MM-DD

## Background

[이 기능이 왜 필요한가. 사용자의 어떤 문제를 푸는가.]

## Goals

- [구체적 목표 1]
- [구체적 목표 2]

## Non-Goals

- [이 디자인이 *다루지 않는* 것]

## Design

### Overview
[큰 그림 — 다이어그램 1개]

### Detailed Design
[데이터 모델·API·UI 등 상세]

## Alternatives Considered

- **[대안 A]**: ... 채택 안 한 이유
- **[대안 B]**: ...

## Migration Plan

[기존 시스템에서 새 디자인으로 가는 경로]

## Risks

- [위험 요소·그 완화 방법]

## Open Questions

- [아직 답이 없는 질문]

디자인 문서가 자주 빠뜨리는 것

  1. Non-Goals
    다루지 않는 것을 명시하지 않으면 리뷰어는 모든 것에 대해 질문합니다. “이 디자인은 결제 도메인만 다룹니다. 환불은 다음 디자인에서”가 한 줄 있으면 검토가 좁아집니다.
  2. Migration Plan
    새 시스템을 만드는 게 아니라 기존 시스템을 변경하는 디자인일 때, 어떻게 옮길지가 빠지면 검토자는 실현 가능성을 의심합니다.
  3. Risks와 Open Questions
    RFC와 마찬가지로, 자기 제안의 약점을 쓰는 자리가 가장 자주 빠집니다.
  4. 시점이 흐릿하다.
    ”이렇게 합니다”인지 “이렇게 하면 어떨까요”인지 톤이 일관되지 않으면 검토자는 결정을 누가 내리는지 헷갈립니다. 디자인 문서는 작성자의 제안임을 명확히 합니다.

디자인 문서와 ADR의 관계

좋은 흐름은 다음과 같습니다.

1. Design Doc 작성·리뷰 (1~2주)
   ↓
2. Approved 후 구현 시작
   ↓
3. 구현 중 추가로 결정된 큰 사안 → 별도 ADR
   ↓
4. 구현 완료 후 Design Doc은 archive
   ↓
5. 핵심 결정은 ADR로 박제되어 남는다

디자인 문서를 영구 보존하려 하지 않아도 됩니다. 결정의 박제는 ADR이 맡습니다. 디자인 문서는 과정의 글입니다.

짧은 시나리오 — 디자인 문서가 ADR로 박제되기까지

가상의 PayLite 팀이 환불 자동화 기능을 시작합니다. 두 주의 흐름을 한 장으로 보면 두 문서의 자리가 분명해집니다.

디자인 문서에서 ADR로 이어지는 시간 축 다이어그램. 가로축이 시간이며 세 단계가 마디로 표시된다. 1단계 PROPOSAL: Design Doc 작성 — Background 환불 요청이 결제 트래픽의 8%, Goals 자동 환불 정책, Non-Goals 분쟁 처리는 별도, Design API와 데이터 모델 초안, Alternatives 동기 vs 비동기 처리, Open Questions PG사 응답 지연 시 정책. 상태 Draft → In Review → Approved. 2단계 IMPLEMENT: 구현 1~2 스프린트 — Design Doc은 작업 가이드로 사용되고 PR마다 링크됨. 구현 중 새로 결정된 큰 사안(예: 재시도 정책의 변경, 외부 의존성 추가) 발생. 3단계 ARCHIVE + DECISION: 구현 완료 — Design Doc은 archive 폴더로 이동(상태가 Implemented로 변경), 핵심 결정만 ADR-031 자동 환불 정책 채택으로 박제, ADR의 References에 Design Doc 링크. 다이어그램 하단 노트: 디자인 문서는 결정의 과정, ADR은 결정의 결과. 둘 다 필요하지만 수명이 다르다.

흐름을 풀어 쓰면 이렇습니다.

  1. Design Doc 작성 (2026-04-01 ~ 04-05): 작성자가 5일 동안 초안을 만듭니다. 본문에 Background(환불 트래픽 8%)·Goals·Non-Goals(분쟁 처리는 다음)·Design·Alternatives·Open Questions 가 들어갑니다.
  2. 리뷰 (04-08 ~ 04-12): 팀 동료 4명이 코멘트로 토론. 재시도 정책과 외부 PG사 응답 지연 시 정책이 가장 큰 논점. 결국 동기 처리가 아닌 큐 기반 비동기로 합의.
  3. Approved → 구현 시작 (04-15): Design Doc 상단 상태가 Approved로 변경. 이후 모든 관련 PR에 이 Design Doc 링크가 박힙니다.
  4. 구현 중 새 결정 (04-20): 외부 PG사 응답이 5초 이상 지연될 때 큐에서 재시도 vs 사용자에게 즉시 실패 통지 사이의 결정이 새로 등장. Design Doc에 한 단락 추가하고, 동시에 별도 ADR-029로도 박제 (이 결정은 결제 도메인 전반에 영향을 미치기 때문).
  5. 완료 + Archive (04-28): 기능 출시. Design Doc 상태가 Implemented로 바뀌고 docs/design/archive/로 이동. 같은 날 ADR-031 *“자동 환불 정책 채택”*이 단정적인 톤으로 작성되며 References에 옛 Design Doc 링크.

세 달이 지나 누군가 *왜 우리가 환불을 큐 기반으로 처리하나?*라고 묻습니다. 답은 ADR-031에 있습니다. *어떤 대안을 검토했나?*가 더 깊이 궁금하면 ADR-031의 References를 타고 archive된 Design Doc으로 들어갑니다. 두 문서의 수명이 다른 이유가 여기서 명확해집니다.

보안 문서

보안 문서는 본 시리즈의 다른 문서들과 결이 다릅니다. 공격자도 읽을 수 있다는 가정으로 써야 하기 때문입니다. 그 긴장이 보안 문서의 모든 결정을 만듭니다.

보안 문서는 단일한 한 종류가 아닙니다. 대표적으로 셋이 있습니다.

Threat Model

시스템의 공격 표면과 예상 공격 시나리오를 정리하는 내부 문서. STRIDE, PASTA, ATT&CK 같은 프레임워크가 있습니다.

STRIDE가 가장 자주 시작점입니다:

약어의미
SSpoofing — 가짜 신원
TTampering — 변조
RRepudiation — 행위 부인
IInformation Disclosure — 정보 유출
DDenial of Service — 가용성 공격
EElevation of Privilege — 권한 상승

각 컴포넌트별로 이 여섯 차원에서 어떤 위협이 가능한가, 그것에 어떻게 대처하는가를 적습니다.

Threat Model은 내부 전용 문서입니다. 외부에 공개하지 않습니다.

보안 가이드라인

SQL injection 방지, XSS 방지, secret 관리, 의존성 관리 등 개발자 동료가 코드를 쓰면서 따라야 할 규칙입니다.

이 글은 내부 문서이지만 Reference에 가까운 톤으로 씁니다. “이렇게 하라”, “이건 금지” 같은 단정적 문장.

## Secret 관리

DO:
- 시크릿은 AWS Secrets Manager 또는 1Password에 저장
- 코드에서 env var로 주입
- 시크릿 로테이션 주기: 90일

DON'T:
- 시크릿을 코드에 하드코딩
- 시크릿을 슬랙·이메일·문서에 평문 공유
- .env 파일을 git에 커밋

이런 문서는 예외와 함께 운영됩니다. 모든 규칙엔 깰 때가 있습니다. 깨야 할 때 어떻게 하는지를 같이 적어둡니다.

Security Disclosure Policy (security.txt / SECURITY.md)

가장 공개적인 보안 문서로 외부 보안 연구자가 우리 시스템의 취약점을 발견했을 때 어디로 신고하는가를 정합니다.

# Security Policy

## Supported Versions
| Version | Supported |
| --- | --- |
| 4.x | ✅ |
| 3.x | ✅ (security only) |
| < 3.x | ❌ |

## Reporting a Vulnerability

보안 취약점을 발견하시면 다음으로 연락 부탁드립니다:

- Email: security@example.com (PGP key: ...)
- Bug Bounty: https://hackerone.com/example
- 응답: 48시간 이내 첫 회신

**공개 disclosure 정책**:
- 패치 출시 후 90일 후 또는 합의된 시점에 공개
- CVE 발급 시 함께 발표

**Out of Scope**:
- 사회공학·물리적 공격
- ...

이 문서는 GitHub 저장소 루트의 SECURITY.md 또는 도메인의 /.well-known/security.txt로 둡니다. 외부 보안 연구자가 어디로 가야 할지를 찾을 수 있게. 공개 예로는 GitHub의 SECURITY.md가 사람이 읽는 정책의 표준 형태(Scope·신고 채널·Safe Harbor)를 보여주고, Cloudflare의 security.txt는 같은 정보를 RFC 9116 기계 가독 포맷(Contact · Policy · Canonical · Preferred-Languages)으로 풀어놓은 사례입니다.

security.txt와 그 주변 표준

이 영역에는 읽는 글만이 아니라 기계가 읽는 글도 있습니다.

  • RFC 9116 — security.txt: 도메인의 /.well-known/security.txt에 두는 짧은 텍스트 파일. Contact:, Encryption:, Expires:, Preferred-Languages: 같은 필드가 표준화되어 있습니다. 자동화된 취약점 스캐너·연구자 도구가 어디로 신고할지를 코드로 찾을 수 있게 합니다.
  • GitHub Security Advisories: 저장소의 Security 탭에서 비공개 advisory를 만들고, 비공개 fork에서 패치를 준비해 동시에 공개하는 흐름을 지원합니다. CVE 발급도 GitHub이 대행합니다. 외부 신고 → 비공개 협업 → 공개의 전 과정을 한 곳에서.
  • OWASP ASVS(Application Security Verification Standard): “우리 시스템이 어느 수준의 보안 검증을 통과하는가”를 체크리스트로 정리한 표준. 보안 가이드라인을 처음부터 다 쓸 필요 없이 ASVS의 항목을 인용·발췌해 시작점으로 삼는 팀이 많습니다.

위협의 심각도 표기에서는 CVSS(Common Vulnerability Scoring System)가 사실상 표준입니다. 4.0 / 7.5 / 9.8 같은 단일 점수와 함께 벡터 문자열(예: AV:N/AC:L/PR:N/UI:N/S:U/C:H/I:H/A:H)로 공격 조건까지 표현합니다. SECURITY.md에 “Critical(CVSS 9.0+)은 24시간 안에 첫 회신”처럼 대응 SLA를 묶어두는 게 흔한 패턴입니다.

공개 범위는 누구까지인가

내부 보안 문서의 공개 범위는 의외로 자주 흔들립니다. 한 줄 가이드를 적어두면 결정이 빨라집니다.

  • Threat Model: 보안팀 + 해당 시스템 핵심 담당자(보통 5~15명 이내). 회사 전체 위키에 두지 않습니다.
  • 보안 가이드라인 (SQL injection 방지, secret 관리 등): 전 개발자에게 공개. 모르고 어기는 것을 막는 글이라서 접근이 좁으면 의미가 줄어듭니다.
  • SECURITY.md / security.txt: 전 세계 공개. 외부 연구자가 찾을 수 있어야 의미가 있습니다.
  • 인시던트 보고서: 영향 범위에 따라 내부 공유 vs 공개 RCA로 갈립니다. 사용자 데이터 영향이 있으면 일정 시점 이후 공개를 기본으로 하는 회사가 많습니다(GDPR·개인정보 보호법 등의 통지 의무도 영향).

규칙은 단순합니다. 공격자가 알면 위험한 것은 좁게, 동료가 모르면 위험한 것은 넓게, 법·신뢰가 공개를 요구하는 것은 끝까지 공개. 셋의 경계가 흐릿한 영역은 보안팀의 한 번의 결정으로 잘라둡니다.

보안 문서가 자주 무너지는 지점

  1. Threat Model이 공개된다.
    가장 치명적인 실수입니다. 접근 권한을 처음부터 분리합니다.
  2. 가이드라인에 왜가 없다.
    ”이렇게 하라”만 있으면 예외 상황에서 개발자가 판단할 근거가 없습니다. 짧게라도 왜 그 규칙인지를 적습니다.
  3. SECURITY.md가 없다.
    외부 연구자가 어디로 가야 할지 모르면 공개적으로 트윗하는 사고가 납니다. 모든 공개 저장소에 있어야 합니다.
  4. 보안 가이드와 실제 운영이 다르다.
    가이드는 90일 로테이션인데 실제로는 1년째 그대로면, 가이드가 거짓말이 됩니다. 자동화·점검 주기와 함께 운영합니다.

시리즈를 닫으며

여기까지 아홉 편을 따라오셨다면, 기술문서에 대한 전체 지도가 한 번 펼쳐졌을 것입니다. 마지막으로 시리즈의 큰 원칙을 다시 한 번 짚습니다.

  1. 독자를 정하고 시작하라.
    모든 편의 첫 원칙이었습니다. 누가, 무엇을 알고 있고, 무엇을 하려고 이 문서를 여는가.
  2. 한 문서, 한 의도.
    튜토리얼·하우투·레퍼런스·익스플레네이션의 네 분면이 섞이는 순간 글은 누구에게도 닿지 않습니다.
  3. 예시는 상상하는 것보다 강하다.
    막힐 때마다 예시로 돌아갑니다.
  4. “왜”를 보존하라.
    코드와 diff는 무엇을 알려주지만 왜는 사람만 쓸 수 있습니다. ADR, 커밋 본문, PR 설명, 디자인 문서 — 다 왜의 보존에 관한 글입니다.
  5. 안 쓰는 것도 선택지다.
    문서는 작성하는 것도 비용입니다. 비용을 치를 가치가 있는 곳에만 씁니다. 동시에, 가치가 있는 곳에는 치를 만한 비용을 치릅니다.

기술문서는 부수적인 일이 아닙니다. 엔지니어링의 일부입니다. 시스템의 총 비용을 낮추는 도구이고, 미래의 자신과 동료에게 보내는 비동기 메시지입니다. 코드가 컴퓨터에게 하는 말이라면, 문서는 사람에게 하는 말입니다. 둘 다 우리의 일입니다.

시리즈 전체 목차

참고 자료