Ping Identity는 기업용 아이덴티티, 액세스 관리를 서비스하는 기업입니다. 근무하는 인원은 약 2500명인데, 테크니컬 라이터가 32명이라고 합니다. 여기에 2명의 에디터가 있고, 4명의 콘텐츠 엔지니어, 3명의 관리자가 있다고 합니다. 회사 규모에 비해 상당히 많은 인원이고, 에디터가 있다는 것이 정말 대단한 일입니다. 발표자는 럭셔리한 환경이라고 표현하네요.
2023년에 비슷한 일을 하는 ForgeRock을 인수했는데, 문서팀에는 2가지 전혀 다른 문서화 프로세스를 통합해야 하는 미션이 생겼습니다.
Ping은 DITA 기반으로 문서를 작성하고 있었고, ForgeRock은 Docs as Code 형식으로 관리하고 있었습니다. 전혀 다른 형식이라 어느 한쪽으로 프로세스를 정해야 했고 Docs as Code 형식을 따르기로 했습니다. 이런 전환은 빠르게 진행되어야 했습니다. 그렇지 않으면 문서 작성자들이 2가지 프로세스 사이에서 계속 힘들어할 수 있기 때문이죠.
기존 DITA 기반 데이터를 전환하는 것은 엔지니어의 도움이 컸습니다. XSLT 파일을 AsciiDoc으로 전환하는 스크립트를 작성하고 약 48,000페이지 분량의 문서를 이관했습니다. XSLT 파일을 AsciiDoc으로 전환하는 유료 도구들이 있긴 하지만 아마도 Ping 내부적인 스크립트 등으로 포함하고 있어서 직접 만들기로 한 것이 아닌가 싶네요.
Docs as Code 프로세스를 위한 도구도 선정해야 했습니다. 기존 도구를 사용하지만, Ping에서 주도권을 가져갈 수 있는 프로세스를 구성하고 싶었다고 합니다.
- 웹사이트: Astro.js 기반으로 만들었습니다. 디자인팀에서 전반적인 디자인은 기업 이미지에 맞게 작업해 주었고 나머지는 문서팀 엔지니어들이 작업을 했습니다.
- 웹사이트 운영: Google Cloud Platform에 올려서 운영합니다. 직접 운영하는 것보다 비용이 절감될 수 있다고 하네요(뭐, 이건 상황에 따라 다를 것 같긴 합니다).
- 파이프라인: ForgeRock에서 사용하던 Jenkins 프로세스를 일부만 수정해서 사용할 수 있었습니다.
문서 빌드 방식과 관련 도구에 대해서는 좀 더 상세하게 설명해주었습니다.
1. Documentation Build Overhaul (문서 빌드 방식 개선)
- 복잡한 방식에서 간단한 방식으로 변경
원래는 Maven이라는 복잡한(아마 상대적으로 무겁다는 이야기 같네요) 도구를 써서 문서를 빌드했는데, 이제는 더 가벼운 스크립트와 Antora라는 도구를 사용해 쉽게 만들 수 있게 바꿨습니다(아직 일부 문서는 Maven 기반으로 빌드를 하고 있는데, 점차 제거해나가고 있다고 합니다).
- 필요한 것 한 번에 설치
예전에는 여러 가지를 따로따로 설치해야 했지만, 이제는 한 번에 필요한 모든 것을 설치할 수 있도록 했습니다(새로운 테크니컬 라이터가 오더라도 관련된 도구를 찾아서 설치하지 않고 하나의 설치 파일로 묶어서 배포한다는 이야기입니다).
- 더 빨라진 빌드
이제는 Maven이나 Docker 같은 무거운 도구 없이 바로 실행할 수 있어서, 문서 만드는 속도가 훨씬 빨라졌습니다(Antora는 로컬에서 빌드를 하기 때문에 빠르다고 합니다).
- 직접 만든 자바스크립트 패키지 사용
문서 만드는 과정을 관리하고, 확장 기능을 설치하고, 필요한 것들을 관리하는 자바스크립트 도구도 직접 만들었습니다.
2. Tooling Updates (도구 업데이트)
- Jenkins 파이프라인 개선
Jenkins라는 자동화 도구의 라이브러리를 새 빌드/배포 방식에 맞게 업데이트했습니다.
- Maven 플러그인 조정
사이트를 옛날 방식과 새 방식 두 가지로 모두 지원할 수 있도록 Maven 플러그인을 수정했습니다(이건 2개 회사의 문서를 합치는 과정이 꽤 시간이 걸리는데 그 사이에도 계속 제품은 업데이트되고 문서도 작성되어야 하기 때문에 그 과정을 지원하기 위한 조치였다고 합니다).
- UX와 협업해 UI 개선
사용자 경험(UX)팀과 함께 문서 사이트의 디자인을 새롭게 바꿨고, 기존 자산(이미지, 스타일 등)을 잘 활용했습니다.
- 검색 기능 강화
Ping Identity의 검색 기능을 넣어서, 익숙하고 편리한 검색 경험을 제공했습니다.
- Jenkins 파이프라인을 전용 서버로 이전
Jenkins 작업을 전용(비공개) 서버에서 하도록 옮겨서, 더 많은 빌드 작업을 효율적으로 처리하고 자원 충돌도 줄였습니다.
2개 회사의 팀을 하나로 합치는 과정에서 고민해야 할 여러 가지를 이야기했는데, 가장 좋은 방법은 함께 할 수 있는 프로젝트를 직접 해보는 것이라고 합니다. 같은 목표를 향해 노력해 보는 경험이 가장 효과적이라고 합니다.
Q&A
- 상세하게 이야기를 하지 않았는데 사용자가 로그인을 하고 문서에 접근하는 경우에는 개인화된 콘텐츠를 제공한다고 합니다.
- 조직 내에서 문서를 제품으로 인식하고 있다고 합니다(물론 실무 엔지니어들의 입장은 다를 수 있지만, 의사결정자들은 그렇게 생각한다고 합니다. 그렇기 때문에 이 정도 규모의 팀을 구성할 수 있는 것이고, 문서팀에서도 문서화가 조직의 이익에 도움이 된다는 데이터를 계속해서 발굴하고 보고한다고 하네요).
- 신규 인력을 채용하기 위한 TO도 결국에는 데이터라고 합니다. 이 정도 규모의 기여를 하고 있고 앞으로 해야 할 일(티켓)이 이렇게 많으니 더 많은 인력이 필요하다는 것입니다. 현재는 엔지니어 대비 18:1 정도로 테크니컬 라이터가 있는데 발표자는 10:1 정도의 수준은 되어야 한다고 생각한다고 합니다.
- CEO에게는 GenAI 시대에 더 많은 정확한 제품 정보가 필요한데 이를 위해서도 테크니컬 라이터가 더 필요하다고 제안했다고 하네요.
10 Unifying Documentation - Jodie Landes
www.flickr.com
https://youtu.be/PcyVsZC30Ig?si=ZSXXj4w08QNVmF9p
