Ryan은 Stripe 문서팀의 엔지니어입니다. 국내에도 라인이나 토스 페이먼츠 같은 경우 문서팀에 소속된 엔지니어가 있죠. 성장하는 조직에서는 수시로 제품에 맞게 문서화 워크플로를 변경해야 할 수 있는데 이런 경우 전담 엔지니어가 있으면 큰 도움이 됩니다. Ryan의 경우는 2016년에 테크니컬 라이터로 합류했고 지금은 문서팀과 엔지니어 지원을 조정하는 역할을 하고 있는 듯합니다.
흔히 문서를 이야기할 때 사용자 경험을 많이 강조하지만 조직이나 제품의 특성에 따라 개발자 또는 테크니컬 라이터(기여자)의 경험 역시 중요합니다. 문서 플랫폼이 필요한 이유는 단지 문서가 사용자에게 전달되는 순간뿐 아니라 문서가 만들어지는 워크플로 자체가 중요하기 때문입니다.
Stripe에서는 문서 사용자 경험을 위해 사용자에 맞춤형 콘텐츠를 제공한다고 합니다. 예를 들어 사용자의 테스트키를 포함한 예시 코드를 생성해준다던지 사용자가 필요한 콘텐츠만 노출하는 형태입니다.
콘텐츠 작성의 생산성이나 기여자들이 손쉽게 참여할 수 있도록 Authoring Experience(AX)가 중요하다고 이야기합니다. @+X 라는 것이 말장난 같은 것이긴 하지만 콘텐츠 작성 도구를 만드는 업체들이 이미 사용하고 있는 표현이라 뭐 새로운 것은 아닙니다. 다만 이것이 특정 도구에 대한 이야기가 아니라 점진적으로 실제 테크니컬 라이터와 기여자에게 도움이 되는 개선 방향이라는 점이 중요한 듯싶네요.
Stripe의 기존 문서는 루비 애플리케이션이었습니다. 풍부한 인터랙션을 지원하기 위한 복잡한 로직으로 구성되어 있고 기능 추가 시에는 ERB 파일을 수정했다고 합니다. 콘텐츠 내에 코드가 포함되어 있다 보니 기술적인 문제 뿐 아니라 보안에도 취약한 상태가 되었고 코드를 잘 모르는 테크니컬 라이터가 문서 작업을 하는데 어려움이 있었다고 합니다. 어떻게 보면 개발자 중심으로 인프라가 만들어지다 보니 뭔가 수정이 필요할 때 엔지니어가 필요했고 문서 콘텐츠를 변경하는 작업이 지연되기도 했다고 하네요.
기술적으로도 콘텐츠 내에 포함된 코드는 테스트나 디버깅에도 취약하고 오류가 발생했을 때 이를 추적하는 것도 어려웠다고 합니다. 이런 문제는 루비 애플리케이션 뿐 아니라 콘텐츠 내에 일회성 코드를 포함하고 있는 모든 패턴에서의 문제이며 이런 일회성 코드를 제거하는 것이 중요하다는 이야기네요.
그래서 이런 문제를 해결하기 위한 방법으로 Markdoc을 만들었습니다. 아~ 이걸 이야기하려고 그 앞에 이런 저런 밑밥을 깔았군요 ^^
(Markdoc은 Stripe에서 2022년 5월 오픈소스로 공개한 마크다운 기반 저작 프레임워크입니다).
https://github.com/markdoc/markdoc
마크다운의 단점 중 하나가 기능이 너무 없다는 것이죠. 간단한 문서 작성에는 큰 문제가 안되는데 구조적이고 계층적인 콘텐츠를 구성하기에는 제약이 있습니다. 하지만 이런 단순함이 마크다운의 장점 중 하나입니다.
Markdoc은 마크다운의 단순함을 훼손시키지 않는 것을 전제로 이를 확장할 수 있게 만들었습니다.
Q&A
Markdoc은 개인 프로젝트에서 시작해서 확장된 것이라고 합니다. 지금은 약 10명 정도 규모의 팀에서 이를 관리하고 있습니다. Ryan이 처음 Stripe에 합류했을 때는 엔지니어는 없었고 테크니컬 라이터도 3명(?) 정도였다고 하네요.
이번 세션은 상당히 빠르게 많은 내용을 다루고 있는데 좀 더 자세한 내용은 지난 9월에 게시된 Stripe 기술 블로그 글에서 확인할 수 있습니다.
https://stripe.com/blog/markdoc
Ryan Paul
Explore writethedocs' photos on Flickr. writethedocs has uploaded 2656 photos to Flickr.
www.flickr.com
