2021.03.24

'기술·문서 부채를 남기지 않으려면' 애자일에서 지식관리가 중요한 이유

Isaac Sacolick | InfoWorld
“철저한 문서보다 제대로 작동하는 소프트웨어가 우선”, 애자일 선언(Agile Manifesto)에 명시된 두 번째 가치다. 이 선언의 서명자들은 기존 폭포수(waterfall) 소프트웨어 개발 프로젝트와 밀접하게 연관된 비즈니스 및 기술 요구사항 문서에 맞서 저항했다.

이들은 많은 소프트웨어 개발 프로젝트에서 이러한 문서가 실패와 좌절을 나타내는 신호라는 사실을 간파했다. 작성하는 데 너무 많은 시간이 걸렸고 이해하기에도 너무 복잡했으며 개발팀이 문서를 검토할 시점이면 이미 내용의 유효기간이 지난 경우가 많았다.
 
ⓒ Getty Images Bank

애자일 방법론의 성공과 인기의 이유 중 하나는 이해관계자와 개발팀의 협업 방식이다. 이해관계자가 (대부분의 경우 개발팀의 의견 반영 없이) 긴 요구사항 문서를 쓰는 대신 지속적인 계획, 사용자 스토리 작성, 스토리 추정, 스프린트 약속 및 기타 애자일과 스크럼 작업에서 계속 협업이 이뤄진다.

그러나 이 원칙을 지나치게 확대해서 애자일팀에는 문서가 필요 없거나 문서를 만들지 않아도 된다고 주장하는 사람도 일부 있다.

이와 같은 주장에는 나름대로 이유가 있다. 특히 이해관계자와 제품 소유자가 개발팀을 신뢰하지 못해 신뢰 대신 세부적인 문서를 요구하는 경우가 그렇다. 또한 지금은 기술자의 개발 플랫폼 및 워크플로우와 통합되는 툴이 있지만, 애자일의 첫 10년 성장기 동안에는 지식 자료를 만들고 유지 관리하고 검색하고 사용하는 과정이 지금처럼 편리하지 않았다.
 

문서를 만들고 유지해야 하는 이유

현재 기업은 과거와는 비교할 수 없을 만큼 많은 소프트웨어를 개발하고 데브옵스팀은 수시로 변경을 릴리스한다. 따라서 지식 관리와 기술 문서 유지보수는 매우 중요하다.

사람들은 데브옵스팀이 API를 만들고 클라우드 네이티브 애플리케이션과 다른 시스템을 통합하고 장기간에 걸쳐 기능을 개선할 것으로 기대한다. 또한 이해관계자는 사고, 보안 문제 또는 기타 결함이 발생하면 애자일팀이 손쉽게 문제를 수정해 변경 사항을 릴리스할 것으로 믿는다.

그러나 앞으로 10년 동안 개발팀이 힘들게 유지하고 개선해야 할 레거시 시스템과 기술 부채를 짊어지는 상황을 원하는 사람은 없다. 소프트웨어 개발 프로젝트에 새로 합류한 개발자가 시스템이 어떻게 움직이는지 문서 없이 학습할 수 있을 것이라는 기대는 비현실적이다.

더구나 데이터 과학자는 마이크로서비스와 애플리케이션에 의해 생성되는 기반 데이터를 사용해 분석과 데이터 시각화, 머신러닝 모델을 만드는 경우가 많다. 데이터 과학자는 데이터를 올바르게 사용하고 애플리케이션이 데이터를 생성하고 업데이트하는 방식을 이해하기 위해 데이터 정의와 비즈니스 규칙에 대한 문서가 필요하다.

마지막으로, 많은 기업이 사용자 인터페이스, 워크플로우, 알고리즘, 비즈니스 로직, 데이터 카탈로그, 시스템 변경에 대한 문서를 요구하는 규제 산업 분야에 속한다. 이들 기업에 문서는 필수다.
 

주 사용 대상과 사용 사례

소프트웨어와 데이터, 아키텍처 문서에는 다음과 같은 여러 소비자와 활용 사례가 있다.
 
  • 마이크로서비스와 애플리케이션 작업을 주로 하면서 종속성과 릴리스에 관해 협업하는 다른 팀이 만든 시스템의 여러 측면도 살펴봐야 하는 개발팀
  • 아키텍처, 워크플로우, 비즈니스 로직, 데이터, 오류 조건을 파악해야 하는 IT 운영, 비즈니스 운영, 정보보안, IT 서비스 관리 전문가 및 사이트 안정성 엔지니어
  • 여정 지도, 웹 분석, 최종 사용자 사용 패턴을 파악해야 하는 제품 소유자, 사용자 경험 전문가, 디자이너, 마케터
  • 보안, 개인정보 보호, 규정 준수를 위해 데이터를 점검해야 하는 데이터 거버넌스 전문가
  • 다운스트림 분석과 머신러닝 모델에서 데이터 품질을 확인하고 마스터 데이터 소스를 구축하고 애플리케이션 데이터 소스를 활용하고자 하는 데이터 과학자, 데이터옵스 엔지니어 및 데이터 스튜어드
  • 조직에 새로 합류해서 전임자가 개발한 코드를 유지 및 강화해야 하는 개발자, 비즈니스 분석가, 테스트 자동화 엔지니어, 데브옵스 엔지니어 등

명명 규칙에 따르고 가독성 높은 코드를 만들고 코드를 문서화하는 것은 현재와 미래의 데브옵스팀에는 유용하지만, 그것만으로는 다른 많은 기능과 사용 사례를 지원하기에는 충분하지 않다.

또한 코드 수준의 문서를 읽기에 앞서 아키텍처와 데이터, API, 비즈니스 로직 및 사용자 인터페이스에 대한 포괄적인 문서가 필요할 가능성이 높은 새로운 데브옵스 팀원을 지원하려면 사용자 스토리에 포함되는 코드 문서 및 요구사항은 부족하다.

최선의 방법은 문서의 이해관계자를 파악하고 이들의 주요 요구 사항에 우선순위를 두는 것이다. 애자일팀은 백로그에서 문서 요구 사항을 아이템화하는 방안을 고려하고 규약에 대해 동의해야 한다. 사용자 스토리에서 문서화가 기대되는 경우 허용 기준을 정의하는 것이 좋다. 예를 들어 개발자가 API를 코딩할 때 API 문서를 만드는 것이 여기에 해당한다.

맞춤형 지라(Jira) 이슈 유형, 애저 데브옵스 작업 항목 유형 또는 기타 카드 유형을 스크럼 백로그에 설정해서 문서화를 표시하는 것도 좋은 방법이다.
 

지식 관리와 문서화 툴의 표준화

코드 문서를 읽을 수 있는 것은 데브옵스팀밖에 없으므로 IT 리더십은 모든 이해관계자의 요구 사항에 대처할 지식 관리 툴, 정보 아키텍처 및 문서 표준을 정의해야 한다.

필자는 신생 기업 CTO와 대기업 CIO를 거치면서 툴과 표준에 대한 확고한 생각을 하게 됐다. 조직은 마이크로소프트 365나 구글 워크스페이스를 사용해 문서, 프레젠테이션, 스프레드시트를 만들고 관리할 수 있지만 이러한 툴은 애자일 개발과 데브옵스 팀이 사용하는 지식 자료 플랫폼으로는 그다지 적합하지 않다.

유용한 엔지니어링 문서는 다이어그램과 표, 많은 서식이 적용된 단락이 섞인 형태인 경우가 많다. 일반적인 오피스 애플리케이션은 최선의 옵션이 아니다.

또한 문서 간의 연결이 문서 자체보다 더 유용한 때도 많다. 예를 들어 데이터 과학자는 다이어그램 하나로 시작해 서비스를 클릭해 API를 살펴본 다음 애플리케이션 데이터 소스를 올바르게 활용하는 방법을 알아보기 위해 데이터 사전에 연결할 수 있다.

필자는 IT와 데브옵스 팀에게 워크플로우에 연결되고 풍부한 정보 아키텍처를 지원하고 모든 이해관계자가 소비할 수 있는 문서를 생성하는 지식 관리 툴을 찾을 것을 권장한다.

예를 들면 아틀라시안 컨플루언스(Atlassian Confluence)는 최근 인포월드(InfoWorld) 2021 올해의 기술 상을 수상한 지식 관리 툴이다. 6만 곳 이상의 기업이 문서, 지식 공유를 위해 컨플루언스의 엔터프라이즈 위키를 사용하고 컨플루언스 템플릿을 활용해 협업한다.

지라 소프트웨어를 사용하는 개발팀은 지라 매크로(Jira Macro)를 사용해 백로그의 맞춤형 보기를 생성하고, 그리피(Gliffy), 미로(Miro), 발사믹(Balsamiq), draw.io, 루시드차트(Lucidchart)와 같은 툴을 사용해 위키 페이지에 다이어그램을 포함할 수 있다.

데브옵스 팀 사이에서 인기 있는 그 외의 문서 및 지식 공유 툴로는 마이크로소프트 팀즈(Temas) 위키와 파일 공유, 마이크로소프트 셰어포인트, BMC의 컴어라운드(ComAround), 서비스나우 날리지 매니지먼트(ServiceNow Knowledge Management), 프로프로스 날리지 베이스(ProProfs Knowledge Base) 및 기타 지식 관리 툴이 있다.

비트(Bit), 이글루(Igloo), 자이브(Jive), 럼앱스(LumApps), 심플러(Simpplr)와 같이 지식 공유에 초점을 둔 문서 협업 툴 및 포털에 관심을 두는 기업도 있다.

개발팀은 특수한 기술을 문서화하기 위한 툴도 고려해야 한다. 예를 들어 데브옵스는 API 문서화에 스웨거(Swagger)를 사용하거나 리졸브 인사이트(Resolve Insight)의 디스커버리 앤 디펜던시 매핑(Discovery and Dependency Mapping)을 사용해 하이브리드 클라우드 인프라 구성을 캡처하고 클라우드 아키텍처 다이어그램 툴을 사용할 수 있다.

데이터 과학, 셀프 서비스 데이터 시각화, 데이터 거버넌스, 데이터옵스, 머신러닝 및 기타 분석 기능을 구축하는 기업이라면 데이터 카탈로그를 중앙화해야 한다.
 

문서 표준과 워크플로우 구축

사용 대상을 파악하고 문서화 백로그를 우선 순위화하고 툴을 선택했다면 이제 문서 표준과 템플릿을 만들 차례다. 데브옵스팀은 문서를 만들 때 최종 사용자를 염두에 둬야 한다. 문서 및 정보 아키텍처에 대한 표준이 없으면 콘텐츠를 중앙화해도 유용성이 떨어질 수 있다.

문서 생성과 유지에 애자일 방식을 적용한다면 최종 사용자가 요청하고 제품 소유자가 중시하는 문서에 대한 허용 기준을 정의할 때 최종 사용자의 도움을 요청하라. 문서를 전달하는 시점에서 고객 만족도를 평가하고 그 점수를 문서 표준을 위한 가이드로 활용할 수 있다. 점수가 높은 문서는 이후 문서화에 사용할 템플릿이 될 수 있다.

정의해야 할 또 다른 표준은 누가, 언제 문서를 만들고 업데이트하고 유지할지에 관한 것이다. 빈번한 릴리스를 추구하는 데브옵스팀이 오래된 문서를 방치하거나 문서 부채를 남기는 것은 무책임하다. 최선의 방법은 릴리스 및 변경 관리 프로세스의 일부로 문서 표준과 기대치를 정의하는 것이다.

지금까지 살펴본 것처럼 지속 가능한 애자일 개발과 데브옵스, 데이터 과학을 추구하는 기업은 지식 공유 거버넌스 및 실행 방안을 만들어야 한다. 기술은 빠르게 변하고 기술자는 새로운 과제에 착수하기를 원한다. 문서와 지식 공유를 중시하는 문화를 조성하는 것은 장기적으로 기업이 성공하기 위한 필수 조건이다. editor@itworld.co.kr
 
 


2021.03.24

'기술·문서 부채를 남기지 않으려면' 애자일에서 지식관리가 중요한 이유

Isaac Sacolick | InfoWorld
“철저한 문서보다 제대로 작동하는 소프트웨어가 우선”, 애자일 선언(Agile Manifesto)에 명시된 두 번째 가치다. 이 선언의 서명자들은 기존 폭포수(waterfall) 소프트웨어 개발 프로젝트와 밀접하게 연관된 비즈니스 및 기술 요구사항 문서에 맞서 저항했다.

이들은 많은 소프트웨어 개발 프로젝트에서 이러한 문서가 실패와 좌절을 나타내는 신호라는 사실을 간파했다. 작성하는 데 너무 많은 시간이 걸렸고 이해하기에도 너무 복잡했으며 개발팀이 문서를 검토할 시점이면 이미 내용의 유효기간이 지난 경우가 많았다.
 
ⓒ Getty Images Bank

애자일 방법론의 성공과 인기의 이유 중 하나는 이해관계자와 개발팀의 협업 방식이다. 이해관계자가 (대부분의 경우 개발팀의 의견 반영 없이) 긴 요구사항 문서를 쓰는 대신 지속적인 계획, 사용자 스토리 작성, 스토리 추정, 스프린트 약속 및 기타 애자일과 스크럼 작업에서 계속 협업이 이뤄진다.

그러나 이 원칙을 지나치게 확대해서 애자일팀에는 문서가 필요 없거나 문서를 만들지 않아도 된다고 주장하는 사람도 일부 있다.

이와 같은 주장에는 나름대로 이유가 있다. 특히 이해관계자와 제품 소유자가 개발팀을 신뢰하지 못해 신뢰 대신 세부적인 문서를 요구하는 경우가 그렇다. 또한 지금은 기술자의 개발 플랫폼 및 워크플로우와 통합되는 툴이 있지만, 애자일의 첫 10년 성장기 동안에는 지식 자료를 만들고 유지 관리하고 검색하고 사용하는 과정이 지금처럼 편리하지 않았다.
 

문서를 만들고 유지해야 하는 이유

현재 기업은 과거와는 비교할 수 없을 만큼 많은 소프트웨어를 개발하고 데브옵스팀은 수시로 변경을 릴리스한다. 따라서 지식 관리와 기술 문서 유지보수는 매우 중요하다.

사람들은 데브옵스팀이 API를 만들고 클라우드 네이티브 애플리케이션과 다른 시스템을 통합하고 장기간에 걸쳐 기능을 개선할 것으로 기대한다. 또한 이해관계자는 사고, 보안 문제 또는 기타 결함이 발생하면 애자일팀이 손쉽게 문제를 수정해 변경 사항을 릴리스할 것으로 믿는다.

그러나 앞으로 10년 동안 개발팀이 힘들게 유지하고 개선해야 할 레거시 시스템과 기술 부채를 짊어지는 상황을 원하는 사람은 없다. 소프트웨어 개발 프로젝트에 새로 합류한 개발자가 시스템이 어떻게 움직이는지 문서 없이 학습할 수 있을 것이라는 기대는 비현실적이다.

더구나 데이터 과학자는 마이크로서비스와 애플리케이션에 의해 생성되는 기반 데이터를 사용해 분석과 데이터 시각화, 머신러닝 모델을 만드는 경우가 많다. 데이터 과학자는 데이터를 올바르게 사용하고 애플리케이션이 데이터를 생성하고 업데이트하는 방식을 이해하기 위해 데이터 정의와 비즈니스 규칙에 대한 문서가 필요하다.

마지막으로, 많은 기업이 사용자 인터페이스, 워크플로우, 알고리즘, 비즈니스 로직, 데이터 카탈로그, 시스템 변경에 대한 문서를 요구하는 규제 산업 분야에 속한다. 이들 기업에 문서는 필수다.
 

주 사용 대상과 사용 사례

소프트웨어와 데이터, 아키텍처 문서에는 다음과 같은 여러 소비자와 활용 사례가 있다.
 
  • 마이크로서비스와 애플리케이션 작업을 주로 하면서 종속성과 릴리스에 관해 협업하는 다른 팀이 만든 시스템의 여러 측면도 살펴봐야 하는 개발팀
  • 아키텍처, 워크플로우, 비즈니스 로직, 데이터, 오류 조건을 파악해야 하는 IT 운영, 비즈니스 운영, 정보보안, IT 서비스 관리 전문가 및 사이트 안정성 엔지니어
  • 여정 지도, 웹 분석, 최종 사용자 사용 패턴을 파악해야 하는 제품 소유자, 사용자 경험 전문가, 디자이너, 마케터
  • 보안, 개인정보 보호, 규정 준수를 위해 데이터를 점검해야 하는 데이터 거버넌스 전문가
  • 다운스트림 분석과 머신러닝 모델에서 데이터 품질을 확인하고 마스터 데이터 소스를 구축하고 애플리케이션 데이터 소스를 활용하고자 하는 데이터 과학자, 데이터옵스 엔지니어 및 데이터 스튜어드
  • 조직에 새로 합류해서 전임자가 개발한 코드를 유지 및 강화해야 하는 개발자, 비즈니스 분석가, 테스트 자동화 엔지니어, 데브옵스 엔지니어 등

명명 규칙에 따르고 가독성 높은 코드를 만들고 코드를 문서화하는 것은 현재와 미래의 데브옵스팀에는 유용하지만, 그것만으로는 다른 많은 기능과 사용 사례를 지원하기에는 충분하지 않다.

또한 코드 수준의 문서를 읽기에 앞서 아키텍처와 데이터, API, 비즈니스 로직 및 사용자 인터페이스에 대한 포괄적인 문서가 필요할 가능성이 높은 새로운 데브옵스 팀원을 지원하려면 사용자 스토리에 포함되는 코드 문서 및 요구사항은 부족하다.

최선의 방법은 문서의 이해관계자를 파악하고 이들의 주요 요구 사항에 우선순위를 두는 것이다. 애자일팀은 백로그에서 문서 요구 사항을 아이템화하는 방안을 고려하고 규약에 대해 동의해야 한다. 사용자 스토리에서 문서화가 기대되는 경우 허용 기준을 정의하는 것이 좋다. 예를 들어 개발자가 API를 코딩할 때 API 문서를 만드는 것이 여기에 해당한다.

맞춤형 지라(Jira) 이슈 유형, 애저 데브옵스 작업 항목 유형 또는 기타 카드 유형을 스크럼 백로그에 설정해서 문서화를 표시하는 것도 좋은 방법이다.
 

지식 관리와 문서화 툴의 표준화

코드 문서를 읽을 수 있는 것은 데브옵스팀밖에 없으므로 IT 리더십은 모든 이해관계자의 요구 사항에 대처할 지식 관리 툴, 정보 아키텍처 및 문서 표준을 정의해야 한다.

필자는 신생 기업 CTO와 대기업 CIO를 거치면서 툴과 표준에 대한 확고한 생각을 하게 됐다. 조직은 마이크로소프트 365나 구글 워크스페이스를 사용해 문서, 프레젠테이션, 스프레드시트를 만들고 관리할 수 있지만 이러한 툴은 애자일 개발과 데브옵스 팀이 사용하는 지식 자료 플랫폼으로는 그다지 적합하지 않다.

유용한 엔지니어링 문서는 다이어그램과 표, 많은 서식이 적용된 단락이 섞인 형태인 경우가 많다. 일반적인 오피스 애플리케이션은 최선의 옵션이 아니다.

또한 문서 간의 연결이 문서 자체보다 더 유용한 때도 많다. 예를 들어 데이터 과학자는 다이어그램 하나로 시작해 서비스를 클릭해 API를 살펴본 다음 애플리케이션 데이터 소스를 올바르게 활용하는 방법을 알아보기 위해 데이터 사전에 연결할 수 있다.

필자는 IT와 데브옵스 팀에게 워크플로우에 연결되고 풍부한 정보 아키텍처를 지원하고 모든 이해관계자가 소비할 수 있는 문서를 생성하는 지식 관리 툴을 찾을 것을 권장한다.

예를 들면 아틀라시안 컨플루언스(Atlassian Confluence)는 최근 인포월드(InfoWorld) 2021 올해의 기술 상을 수상한 지식 관리 툴이다. 6만 곳 이상의 기업이 문서, 지식 공유를 위해 컨플루언스의 엔터프라이즈 위키를 사용하고 컨플루언스 템플릿을 활용해 협업한다.

지라 소프트웨어를 사용하는 개발팀은 지라 매크로(Jira Macro)를 사용해 백로그의 맞춤형 보기를 생성하고, 그리피(Gliffy), 미로(Miro), 발사믹(Balsamiq), draw.io, 루시드차트(Lucidchart)와 같은 툴을 사용해 위키 페이지에 다이어그램을 포함할 수 있다.

데브옵스 팀 사이에서 인기 있는 그 외의 문서 및 지식 공유 툴로는 마이크로소프트 팀즈(Temas) 위키와 파일 공유, 마이크로소프트 셰어포인트, BMC의 컴어라운드(ComAround), 서비스나우 날리지 매니지먼트(ServiceNow Knowledge Management), 프로프로스 날리지 베이스(ProProfs Knowledge Base) 및 기타 지식 관리 툴이 있다.

비트(Bit), 이글루(Igloo), 자이브(Jive), 럼앱스(LumApps), 심플러(Simpplr)와 같이 지식 공유에 초점을 둔 문서 협업 툴 및 포털에 관심을 두는 기업도 있다.

개발팀은 특수한 기술을 문서화하기 위한 툴도 고려해야 한다. 예를 들어 데브옵스는 API 문서화에 스웨거(Swagger)를 사용하거나 리졸브 인사이트(Resolve Insight)의 디스커버리 앤 디펜던시 매핑(Discovery and Dependency Mapping)을 사용해 하이브리드 클라우드 인프라 구성을 캡처하고 클라우드 아키텍처 다이어그램 툴을 사용할 수 있다.

데이터 과학, 셀프 서비스 데이터 시각화, 데이터 거버넌스, 데이터옵스, 머신러닝 및 기타 분석 기능을 구축하는 기업이라면 데이터 카탈로그를 중앙화해야 한다.
 

문서 표준과 워크플로우 구축

사용 대상을 파악하고 문서화 백로그를 우선 순위화하고 툴을 선택했다면 이제 문서 표준과 템플릿을 만들 차례다. 데브옵스팀은 문서를 만들 때 최종 사용자를 염두에 둬야 한다. 문서 및 정보 아키텍처에 대한 표준이 없으면 콘텐츠를 중앙화해도 유용성이 떨어질 수 있다.

문서 생성과 유지에 애자일 방식을 적용한다면 최종 사용자가 요청하고 제품 소유자가 중시하는 문서에 대한 허용 기준을 정의할 때 최종 사용자의 도움을 요청하라. 문서를 전달하는 시점에서 고객 만족도를 평가하고 그 점수를 문서 표준을 위한 가이드로 활용할 수 있다. 점수가 높은 문서는 이후 문서화에 사용할 템플릿이 될 수 있다.

정의해야 할 또 다른 표준은 누가, 언제 문서를 만들고 업데이트하고 유지할지에 관한 것이다. 빈번한 릴리스를 추구하는 데브옵스팀이 오래된 문서를 방치하거나 문서 부채를 남기는 것은 무책임하다. 최선의 방법은 릴리스 및 변경 관리 프로세스의 일부로 문서 표준과 기대치를 정의하는 것이다.

지금까지 살펴본 것처럼 지속 가능한 애자일 개발과 데브옵스, 데이터 과학을 추구하는 기업은 지식 공유 거버넌스 및 실행 방안을 만들어야 한다. 기술은 빠르게 변하고 기술자는 새로운 과제에 착수하기를 원한다. 문서와 지식 공유를 중시하는 문화를 조성하는 것은 장기적으로 기업이 성공하기 위한 필수 조건이다. editor@itworld.co.kr
 
 


X