참고한 글
🎁 Resources for paid subscribers
You've seen the tips, now get the tools to master them.
strategizeyourcareer.com
왜 그런 결정을 했을까요?
팀의 특성상 PoC(Proof of Concept)로 작은 프로젝트를 진행한 경험이 많습니다.
PoC의 특성상 최신 기술이 활용될 때가 많았고, 생소한 소프트웨어 툴들이 빈번하게 언급됩니다.
팀에 공유할 때, 팀장님께 보고할 때, 부서장에 보고할 때... 이 상황에서 다들 왜 그런 결정을 했는지 물어보는 경우가 많습니다.
난 왜 그런 경험을 할 때마다 구두로 대체하려고 했을까하는 후회를 하게 만들어준 글입니다.
그런 결정들을 문서로 관리하고 readMe에 남기거나,
노션에 남겨서 진입점만 두고 해당 페이지를 띄워서 설명하면 참 좋았을 텐데 말이죠.
해당 글은 읽어보면 저자의 ADR 템플릿 광고처럼 보이는 글이지만 ADR과 관련된 꾸준한 메시지에는 좋은 의미가 담겨 있습니다.
ADR : Architectural Decision Record
설계 결정 기록물로 중대한 결정에 남기는 문서입니다.
회사의 특성상 어떤 업무의 담당자가 항상 있으면 좋겠지만 그런 일은 드뭅니다. (이직, 퇴사, 업무 변경 등등..)
그러다 보니 어떤 결정들에 대한 이력을 자세하게 듣는 일은 쉽지 않습니다.
중대한 사안의 경우 엔지니어링 팀원들이 모여서 해당 결정과 관련된 뜨거운 논의를 진행하곤 합니다.
(왜 이런 결정이 발생했는가, 기획은 누구인가, 담당자는 누구인가, 디자이너는 누구인가.. 갈아엎자, 새로 만들자)
시간적으로 피로한 일들이 발생하고 작은 질문에서 끝나지 않는 꼬리 질문이 이어지면서 시간대비 효율적이지 못한
논의를 진행하게 됩니다. [특히 프로젝트에 기한이 잡혀있는 경우 더 예민한 상황으로 진행됩니다.]
ADR은 중대한 설계 결정에 대한 "구조적"이고 "쉽게 참조할 수 있는 형태의 문서"입니다.
노션에 ADR Template만 검색해도 많은 템플릿들이 검색에 노출됩니다. (유료가 많습니다..ㅎ)
Lightweight ADRs for Engineering Leaders Template | Notion Marketplace
Lightweight ADR template for capturing important architectural decisions, their context, and consequences. | Discover new ways to use Notion across work and life.
www.notion.so
ADR 템플릿에 대한 이력관리
ADR 템플릿 작성시 유의해야 할 체크 리스트
ADR 템플릿을 어떻게 사용할지 등등
readMe가 프로젝트에 대한 전체적인 이해를 돕는 요약 문서가 되어준다면,
ADR은 해당 프로젝트의 굵직한 결정들에 대한 문서가 되어줍니다.
ADR에서는 What과 Why 두 가지를 매우 중요한 요소로 관리합니다.
ADR의 목표는 해당 문서를 보는 사람들로 하여금 어떤 결정의 배경을 이해하고, 그 배경에 대해서 다시 논의하는 과정을 줄여내는 것이기 때문입니다. (결정들에 대한 가교가 되어주는 것입니다.)
ADR 작성 팁
간결하게 작성한다. (Be Concise)
ADR은 명확하고 간결할수록 더 효과적입니다.
결정을 이해하는데 필요한 핵심 정보(내용)만 기록합니다.
표준 포맷을 사용하자 (Use a Standarized Format)
일관성 있는 표준 포맷을 통해 쉽게 생성하고, 쉽게 작성하고, 쉽게 참조할 수 있도록 만듭니다.
(노션의 버튼 템플릿을 이용하면 쉽게 표준 포맷의 ADR 템플릿을 만들 수 있습니다.)
토의 내용은 분리해서 참조하자
결정 과정에서 긴 논의 결과물이 있는 경우, ADR에 결과물에 참조만 걸어서 관리하도록 합니다.
ADR에는 결정과 왜 결정헀는지에 대한 핵심만 관리하는 것이 중요합니다.
"개발자에서 아키텍트로"라는 도서를 정리한 기록에 ADR이 남아있습니다.
실용주의 프로그래머 시리즈 책으로 2021년에 읽었네요.. [중요한 정보를 기록하는 게 정말 중요하군요]
이 책의 챕터 11부터 ADR이 자주 소개됩니다.
결정을 내릴때마다 아키텍처 의사결정 기록물을 하나씩 기록하라고 소개되어 있습니다.
위의 글과 유사하게 핵심과 간결함에 집중하라는 팁이 있습니다.
형식보다는 "핵심"과 "간결함"이 더 중요하다.
[ 해결방법의 요약, 주요 기능 요구사항 요약, ADR의 간단한 설명, 사용한 아키텍처 스타일과 패턴 ]
1. 전체적인 "해결 방법의 요약"
2. 기술적인 제약 목록
3. 주요 기능 요구사항의 요약
4. 품질 속성의 우선순위 목록
5. 설계 의사결정의 간단한 설명. 논리적 근거와 트레이드오프
6. 사용한 아키텍터 스타일과 패턴
소프트웨어 아키텍트라면 관리해 볼 만한 문서가 아닐까 생각합니다. :)
'IT 고찰 > 좋은 글' 카테고리의 다른 글
| EU 인공지능 법안 요약본 [GPAI: General Purpose AI] (7) | 2024.09.13 |
|---|---|
| [DB] 마이크로서비스에서 공유형 DB를 사용한다는 것 (3) | 2024.09.03 |
| Anthrophic에서 시스템 프롬프트를 공개하다 (0) | 2024.08.29 |
