tag · 10 posts

#documentation

아키텍처 정의서는 왜 화석이 되거나 거짓말이 되는가 - 두 개의 아키텍처 정의서 ep.00
  • series
  • cover
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • c4
  • adr

아키텍처 정의서는 왜 화석이 되거나 거짓말이 되는가 - 두 개의 아키텍처 정의서 ep.00

같은 시스템을 내부 공유용과 SI 납품용, 두 개의 정의서로 나란히 작성하며 비교하는 시리즈입니다. 첫 편에서는 아키텍처 문서가 실패하는 두 가지 방식을 정의하고, 시리즈 전체가 사용할 샘플 시스템을 소개합니다. 이 시리즈가 끝나면 자신만의 정의서를 설계할 기준틀을 갖게 됩니다.

read →
아키텍처 문서의 표준 지형도 - 두 개의 아키텍처 정의서 ep.01
  • series
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • c4
  • adr
  • arc42

아키텍처 문서의 표준 지형도 - 두 개의 아키텍처 정의서 ep.01

아키텍처 문서를 다루는 네 가지 표준 도구를 정리합니다. ISO/IEC/IEEE 42010은 문서가 답해야 할 질문의 틀을, arc42는 문서의 골격을, C4는 다이어그램을 그리는 법을, ADR은 결정의 기록 형식을 정합니다. 같은 도구를 내부용과 납품용이 어떻게 다르게 쓰는지도 함께 봅니다.

read →
요구사항에서 시작하기, 품질 속성과 드라이버 - 두 개의 아키텍처 정의서 ep.02
  • series
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • quality-attributes

요구사항에서 시작하기, 품질 속성과 드라이버 - 두 개의 아키텍처 정의서 ep.02

기능 요구사항은 거의 어떤 구조로도 만족됩니다. 구조를 가르는 것은 가용성·성능·보안 같은 품질 속성과 제약입니다. 이 편에서는 품질 속성을 시나리오로 표현하는 법을 익히고, 스폿의 드라이버 여섯 가지를 도출한 뒤, 그것이 어떻게 설계 결정으로 이어지는지 추적합니다.

read →
뷰를 그리다, C4와 4+1 - 두 개의 아키텍처 정의서 ep.03
  • series
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • c4
  • diagram

뷰를 그리다, C4와 4+1 - 두 개의 아키텍처 정의서 ep.03

하나의 시스템을 여러 관점으로 나눠 그리는 법을 다룹니다. 4+1 뷰 모델로 누가 무엇을 보는지 가르고, C4의 컨테이너 뷰로 스폿의 구조를, 런타임 뷰로 동기와 비동기 두 경로가 갈라지는 순간을, 배포 뷰로 코드가 어디서 도는지를 그립니다. 같은 그림을 두 문서가 어떻게 다르게 싣는지도 비교합니다.

read →
결정을 남기다, ADR - 두 개의 아키텍처 정의서 ep.04
  • series
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • adr
  • decision-record

결정을 남기다, ADR - 두 개의 아키텍처 정의서 ep.04

ADR은 하나의 설계 결정을 맥락·결정·대안·결과로 남기는 형식입니다. 스폿의 여섯 가지 결정을 ADR로 적고, 결정에도 상태와 수명이 있다는 점을 상태 머신으로 봅니다. 같은 ADR이 내부용에서는 살아있는 로그로, 납품용에서는 요구사항에 매핑되는 목록으로 갈라지는 지점도 다룹니다.

read →
흩어진 정책을 모으다, 횡단 관심사 - 두 개의 아키텍처 정의서 ep.05
  • series
  • develop
  • backend
  • frontend
  • infra
  • architecture
  • documentation
  • security
  • observability

흩어진 정책을 모으다, 횡단 관심사 - 두 개의 아키텍처 정의서 ep.05

횡단 관심사는 여러 컴포넌트에 걸치는 정책입니다. 한 곳에 모아 두지 않으면 컴포넌트마다 다르게 구현되고 어딘가에서는 빠집니다. 이 편에서는 스폿의 여섯 가지 횡단 관심사를 관심사와 컴포넌트의 매트릭스로 정리하고, 같은 외부 의존이라도 동기와 비동기 경로에서 에러 전략이 어떻게 갈라지는지 봅니다.

read →
내부 공유용 정의서, 거짓말하지 않는 문서 만들기 - 두 개의 아키텍처 정의서 ep.06
  • series
  • develop
  • backend
  • frontend
  • infra
  • devops
  • architecture
  • documentation
  • adr

내부 공유용 정의서, 거짓말하지 않는 문서 만들기 - 두 개의 아키텍처 정의서 ep.06

지금까지 모은 재료로 내부 공유용 정의서를 완성합니다. 핵심 과제는 두 번째 죽음, 거짓말을 막는 것입니다. 거짓말이 자라는 메커니즘을 짚고, 천천히 변하는 것만 직접 쓰기·다이어그램을 코드로 그리기·결정을 쌓기·검증을 자동화하기라는 네 원칙으로 거짓말할 수 없는 구조를 만듭니다.

read →
SI 납품용으로 변환하기, 화석을 인정하는 문서 만들기 - 두 개의 아키텍처 정의서 ep.07
  • series
  • develop
  • backend
  • infra
  • devops
  • architecture
  • documentation
  • adr

SI 납품용으로 변환하기, 화석을 인정하는 문서 만들기 - 두 개의 아키텍처 정의서 ep.07

살아 있던 내부용 정의서를 SI 납품용으로 변환합니다. 납품용은 살릴 수 없는 문서, 곧 화석입니다. 요구사항 추적표를 채우고, 버전과 승인 이력을 붙이고, 특정 시점에 박제합니다. 공공 SI의 감리·검수 맥락을 짚고, 인수인계를 통해 화석이 유지보수팀의 살아있는 문서로 다시 태어나는 흐름까지 그리며 시리즈를 닫습니다.

read →
왜, 무엇을, 어떻게 - 개발자를 위한 기술문서 입문 ep.00
  • series
  • cover
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • technical-writing
  • documentation
  • diataxis

왜, 무엇을, 어떻게 - 개발자를 위한 기술문서 입문 ep.00

기술문서를 안 써본 개발자가 가장 자주 겪는 문제는 형식이 아니라 의도입니다. 이 시리즈는 Diátaxis 프레임워크로 문서의 좌표를 잡고, 실무에서 실제로 마주치는 여덟 가지 산출물을 한 편씩 다룹니다. ep.00은 그 지도를 펴 보이는 편입니다.

read →
프로젝트의 첫인상, README - 개발자를 위한 기술문서 입문 ep.01
  • series
  • develop
  • frontend
  • backend
  • infra
  • devops
  • ai
  • readme
  • documentation
  • open-source

프로젝트의 첫인상, README - 개발자를 위한 기술문서 입문 ep.01

README는 한 글이 아니라 여러 글의 시작점입니다. 평가자·사용자·기여자라는 세 유형의 독자를 30초·5분·30분이라는 시간 축으로 갈라보고, Hero / Quick Start / Deep 세 구간으로 골격을 잡습니다. 좋은 예와 나쁜 예, 그리고 체크리스트까지.

read →