DX 엔지니어이고 문서화에 필요한 엔지니어링 작업을 합니다. 테크니컬 라이터와 같이 왔다고 소개하는데 아마도 Christina Ausley를 이야기하는 것 같네요. 인상적인 것은 프레젠테이션 자료를 수채화처럼 직접 그려서 작성했습니다(이렇게 그려주는 도구가 있을지도 모르겠으나, 그림체로 보면 직접 그린 것이 맞습니다).
7 버전(C7)은 Hugo 기반으로 작성됐는데 8 버전(C8)으로 올리면서 전반적인 문서의 내용이 변경됐고 문서화 플랫폼도 도큐사우르스로 바꾸었다고 합니다. 문서팀은 4명으로 구성되어 있는데 3명이 테크니컬 라이터이고 1명이 엔지니어입니다.
문서화 플랫폼을 바꾼 이유는 검색 품질 때문이었다고 합니다. 2021년 초에는 "BPMN"이라는 키워드에 대해 20개의 결과가 나왔다면 점점 줄어들어 2022년에는 한 건의 결과도 나오지 않았습니다. C7 문서 검색은 구글에서 제공하는 검색 API를 사용하고 있었습니다. 그리고 C7 문서의 특징은 각 버전별 문서가 모두 온라인에 공개되어 있다는 겁니다. 7.0 버전부터 7.22 버전까지 모두 온라인으로 접근할 수 있습니다. 릴리스는 6개월 단위이고 계속 새로운 릴리스 버전이 추가됩니다. 버전에 따라 "BPMN" 관련 문서가 변경될 수도 있지만 대부분의 경우 인접한 버전에서는 차이가 없을 수도 있습니다.
구글 검색 엔진은 중복된 문서가 있는 경우 표준(canonical) 문서를 선택해 이를 기준으로 결과를 보여줍니다. C7 문서처럼 버전마다 중복된 문서가 작성된 경우에는 가장 많이 사용자들이 참고하는 문서를 표준으로 결정합니다. 예를 들어 최신 문서가 아닌 7.20 문서가 표준이 될 수 있는 것이죠.
때문에 이런 문제를 방지하기 위해 2021년 초 최신 버전을 제외한 나머지 문서에 "noindex" 메타 태그를 추가했습니다. 의도한 것은 7.20 문서가 아닌 7.22 문서를 표준으로 처리하도록 하는 것이었는데 구글 검색 엔진은 여전히 7.20 문서를 표준으로 처리했습니다. 하지만 7.20 문서는 인덱스를 생성하지 않았기 때문에 검색 결과는 나오지 않았던 것이죠.
이를 해결하기 위해 최신 문서에만 canonical 힌트 태그를 추가했고 사이트맵도 최신 문서만 가리키도록 수정했습니다. 그리고 "noindex" 메타 태그는 삭제했습니다. 그리고 최신 문서가 공개됐을 때 이제야 정상적으로 구글 엔진에서 최신 문서를 표준으로 처리하게 됐습니다.
C8 문서는 도큐사우루스로 전환하면서 이런 검색 문제에 대한 경험을 적극적으로 활용했습니다. 사이트맵이나 표준 문서 힌트 태그가 처음부터 적용되도록 설정했습니다.
좀 더 자세한 내용은 아래 링크를 참고하세요.
https://www.stevenhicks.me/blog/2024/04/how-camunda-docs-handle-canonicals/
프레젠테이션은 직접 그린 것이 맞다고 합니다. Q&A 세션에서 사진을 보여주었구요. 한 가지 팁은 그림을 촬영할 때 같은 느낌으로 촬영될 수 있도록 임의의 액자를 만들고 그곳에서 고정된 상태로 촬영하라는 것입니다.
그리고 Hugo에서 도큐사우루스로 전환한 건 본인이 결정한 것이 아니라서 왜 그렇게 했는지는 모르겠다고 하네요 ^^
https://youtu.be/pQJBFn4tomA?si=ktZaiyv1ucxiTG08
Steven Hicks - Misadventures
www.flickr.com
