코딩으로 문서 작성하는 콰르토(Quarto) 톺아보기

법률용어사전에서는 “업무”라는 단어를 아래처럼, “반복되어 행해지는 일”이라 표현하고 있습니다. 개인적인 주관을 살짝 덧붙여 단순히 일을 해냈다로 끝내는 것을 넘어, 이러한 업무로부터 나온 결과들을 의사결정권자나 동료, 혹은 고객과 같은 다른 사람들에게 “글로써" 전달하는 것 또한 업무의 연장선으로 볼 수 있을 것 같습니다. 

프로젝트 기획서, 개발 문서, 개인 업무 회고록, 조직의 기술 블로그를 위한 아티클 작성, 데이터 분석, 마케팅 리포트 등 우리 일상 업무에는 수많은 글이 쓰이고 있습니다. “문서 작성(publish)”이라고 불리기도 하는 글쓰기는 꼭 개발 직군이 아니더라도, 모두에게 필요하고 도움이 되는 영역 중 하나입니다. 

일기처럼 일회성이거나 다른 사람에게 공개할 일이 많지 않은 개인적인 글이 아니라면, 특히 “업무와 연관된 글”을 담는 문서는 조직이 굴러가는 사이클마다 반복적으로 쓰게 됩니다. 이러한 문서들은 읽는 사람을 고려해야 하기 때문에 형식과 체계가 정해져 있고, 안의 내용만 그때그때 바꾸면서 채우면 되는 경우도 많습니다. 즉 인풋(input)과 아웃풋(output)이 나름의 규칙을 통해 정해져 있는 “함수의 형태로” 볼 수도 있습니다. 

회사에서 특정 프로덕트의 최근 한 달 간 매출, MAU 등의 지표는 어떤 값을 갖는지, 가장 큰 고객 그룹은 누구이고, 지표들이 이전 달 대비 얼마만큼의 변동이 있는지, 유의할 만한 VoC로는 어떤 것들이 있었는지 등의 정보를 정리해서 매월 리포트를 만든다는 가상의 예시를 생각해보겠습니다.

이를 위해 DB나 시트 등을 조회하고, 지표들을 계산한 뒤 그 값들과 시각화한 이미지들을 만들어서 워드에 붙여 넣고, 모바일에서도 볼 수 있게 pdf나 html 혹은 슬라이드 등의 형태로 만드는 업무를 해야 할 것입니다. 이를 매달 반복하는 것은 중요하긴 하지만 동시에 귀찮은 “업무"입니다.

이번 글에서는 문서 작성은 귀찮았지만 영리했던 과거의 누군가의 작품인, 약간만 익숙해지면 다양한 범위의 업무에서도 충분히 활용할 수 있는 문서작성 툴 콰르토(Quarto)를 소개하겠습니다.

문서 작성과 콰르토의 역사

콰르토는 R이라는 프로그래밍 언어에서 마크다운(마크다운)을 작업할 수 있게 하는 R마크다운이라는 툴의 후속작입니다. 노션을 써봤다면 개발자가 아니더라도 이미 마크다운에 금방 적응할 수 있는 사람도 많을 텐데요. 이는 #, -, > 와 같은 키워드를 통해 서식이 있는 문서를 만들 수 있기 때문입니다. (참고로, 크게 중요한 것은 아니지만 콰르토는 “4절판”이라는 출판 용어입니다.)

마크다운은 문법이 쉽고 간단하며 오피스와 같은 프로그램에 의존을 하지 않고도 사용할 수 있다는 장점을 가지고 있기 때문에, 다양한 분야의 산업에서도 많이 활용되었습니다. 그렇기 때문에 마치 HTML처럼 파이썬, R, C, Java 등 다양한 프로그래밍 언어들은 마크다운을 연동하여 사용하게 하는 각자의 방법들이 있었습니다. R마크다운은 이를 위한 툴이었다고 생각하면 좋습니다.

앞서 언급했듯, 마크다운은 쉽고 가볍기 때문에 R마크다운을 기준으로 슬라이드를 만들거나, 웹페이지, 대시보드, 논문, 블로그, 전자책 등 다양한 분야로 응용되고 있었습니다. 

한편 오픈소스라는 R의 특성상 이러한 역할을 하는 툴(패키지라고 부릅니다)들은 하나의 큰 집단에서 관리되기 보단, 수많은 개인들의 기여로 만들어지는 경우가 많았습니다. 그래서 각 목적을 달성하기 위해서는 각각의 툴을 (매번 학습하고) 사용해야 한다는 문제가 나타났습니다. 

이를 위해 R스튜디오(R studio)라는 (R 업계에서는 가장 큰) 조직에서 이 R마크다운 기반의 툴들을 통합하고, 파이썬과 줄리아(julia) 등 데이터 업계에서 R과 같이 활용되는 언어들을 함께 지원하는 콰르토라는 마크다운 기반 문서작성 툴을 만들게 됩니다.

콰르토는 “네가 뭘 좋아할 지 몰라서 다 준비해봤어" 라는 스탠스에 가깝기 때문에 언어와 IDE, 목적 등 다양한 선택지 앞에서 걱정할 필요는 없습니다. 각자에게 필요한 기능만 사용해도 충분하며. 일반적으로 문서와 발표자료, 블로그, 전자책, 대시보드 5개 정도가 자주 활용됩니다. 이번 글에서는 문서를 작성하는 예시를 다뤄보겠습니다.

콰르토로 문서 만들기

콰르토를 사용해서 예시 문서를 만들어보기 위해 준비해야 할 것은 다음과 같습니다. 설치의 경우 보통의 일반적인 프로그램과 비슷하게 홈페이지에서 다운로드하고 클릭을 몇 번 해 진행할 수 있기 때문에 따로 설명하지 않습니다.

1. 콰르토 설치
2. IDE 설치 (메모장과 터미널로 작업해도 무방하지만, IDE가 있는 편이 편리합니다)
3. qmd 작성
4. pdf 로 변환
5. 완성!

콰르토는 qmd라는 틀에 마크다운에 기반한 R, 파이썬 등의 언어로 내용을 채운 뒤, 이를 마크다운으로 변환한 다음 그 마크다운을 다시 여러 목적에 맞는 형태로 변환하는 흐름을 가지고 있습니다.

이러한 변환들은 콰르토가 자동으로 해주지만, 문서를 프로그래밍으로 만들기 위해서는 사용자가 추가로 알아야 할 것이 두 개 있습니다. 바로 마크다운과 YAML인데 각각 qmd를 채우는 용도와 qmd를 다른 형태로 변환하는 니트R(knitR)에서 쓰입니다.

마크다운에서 자주 쓰이는 기본 문법은 아래와 같으며 첨부한 이 링크처럼 웹 기반 마크다운 에디터에서 테스트해볼 수 있습니다.

YAML은 qmd의 상단에서 qmd를 설명하는 역할을 하며 정해진 형식이 있어 이를 반드시 지켜야합니다.

1. 위, 아래를 ‘---‘ 로 감싼다.
2. YAML의 내용들은 “key: value”의 형태로 구성한다.

콰르토에서 예시로 제공되는 qmd 파일을 열고 IDE 기준, RendeR 버튼을 누르면 만들어 낼 수 있는 문서의 결과물의 이미지는 아래와 같습니다. (작가의 깃허브 페이지에서도 볼 수 있습니다.) 

이렇게 콰르토는 마치 붕어빵을 틀에 찍어서 만들어내는 것처럼 코드를 통해서 결과물들을 만들어냅니다. 그래서 동일한 코드를 사용한다면 만드는 사람이나, 시간 그리고 환경 등의 영향을 받지 않고 퀄리티나 형태가 동일한 결과물들을 빠르게 반복하여 만들어낼 수 있습니다. 단, 붕어빵에도 팥과 크림, 치즈, 고구마등을 넣어 변화를 주는 것처럼 데이터나 차트와 같은 내용물은 작성자의 의도에 따라 바꿀 수 있습니다.

예시에서 언급했던 최근 한 달치 데이터 혹은 계산된 지표를 파이썬이나 R을 통해 qmd로 가져올 수 있다면, 이러한 작업을 하는 코드로 구성된 qmd “틀”을 만들어두고 필요할 때마다 보고서를 만들어 반복되는 업무를 상당량 줄일 수 있습니다. 

문서 외의 또 다른 예시로, 콰르토만으로 만들어진 R for Social Scientists라는 블로그를 공유드립니다. (이 블로그 내의 각 페이지와, 내부의 발표자료도 전부 콰르토로 만들어졌으며, 만든 결과물을 온라인에 배포하는 과정에서만 깃허브 페이지를 사용했습니다.)

앞으로의 콰르토

“노션"과 유사한 문법을 사용하는 ①쉬운 마크다운 기반에, ②여러 데이터 분석용 언어의 결과물들 같이 지원하며, ③pdf 부터, 프레젠테이션등 다양한 형태의 결과물을 ④재현가능한 형태로 프로그래밍을 통해 제공하는 콰르토는 낯설지만 익숙해졌을 때 많은 것을 할 수 있게하는 매력적인 툴입니다. 꼭 프로그래밍을 업무에 쓰지 않더라도 활용할 수 있는 여지가 많아, 새해를 맞이하여 한번쯤 배워보는 것을 개인적으로는 아주 추천합니다. (글에 포함되어있던 펭귄 외의 다양한 사용 예시가 궁금하다면 이 링크나, 갤러리를 참조해보는 것도 좋습니다.)

특히 파이썬, 줄리아 같은 다른 언어와 R스튜디오 외에 VSCode나 주피터(jupyter) 등 다양한 IDE를 통해서도 사용할 수 있기 때문에 이전 세대의 R마크다운이 가지고 있던 R 특유의 “배타적인" 성향이 많이 줄었다는 장점도 있습니다.

그러나 콰르토가 가지고 있는 단점도 있습니다.

1. R마크다운의 후속으로 등장한 지 1년 정도가 지난, 개발이 완성된 단계의 툴은 아니기 때문에 아직 지원되지 않는 기능들도 있습니다. 물론 콰르토를 아주 깊게 쓰는 사용자가 아니라면 거의 체감하기 어렵습니다.
2. 콰르토는 다양한 결과물을 제공하는데, 이는 기존의 그 결과물을 제공하는 수많은 프로덕트가 경쟁자라는 의미를 갖습니다. 가령 코드 실행은 주피터, 문서 작성은 노션, 발표자료는 키노트, 대시보드는 스트림릿(streamlit), 전자책은 깃북(gitbook), 블로그는 티스토리와 같은 서비스를 쓸 수 있습니다.
3. 콰르토를 활용하기 위해서 개발자만큼은 아니지만, 아주 작게라도 코딩을 할 수 있어야 합니다. 마크다운 이외에도 설치한 IDE를 통해 qmd 코드를 작성하고, 필요에 따라 수정하여, 이를 결과물로 “publish”하는 과정에서 마우스 만으로 할 수 있는 작업은 한계가 있기 때문입니다.

그럼에도 불구하고 저는 여전히 꼭 학계나 리서치 혹은 데이터 도메인의 직군이 아니더라도 콰르토를 추천합니다. 다만 앞서 언급한 것처럼 장단점이 있는 만큼, 스스로 콰르토를 잘 활용할 수 있는 사람인지 확인하는 체크리스트를 공유하는 것으로 글을 마치겠습니다. 이들 중 2개 이상 해당된다면 콰르토를 한번 “찍먹” 해보시기를 추천합니다.

1. 주기적으로 문서를 만들어야 하고 이 과정에서 시간을 많이 소모하는 사람
2. 형식이 정해진 문서를 반복적으로 만들어야 하는 사람
3. 문서를 만드는 과정에서 코드를 통한 결과물 (시각화)이 포함되면 좋은 사람
4. R이나 파이썬을 데이터 분석이나 문서 자동화 등으로 종종 활용하고 있던 사람
5. 하나의 도구를 학습해서 문서, 블로그, 발표자료등 다양한 형태의 결과물들로 응용하고 싶은 사람

요즘IT의 모든 콘텐츠는 저작권법의 보호를 받는 바, 무단 전재와 복사, 배포 등을 금합니다.