개인적인 정리
Anna Gasparyan는 JetBrains 입사 8년 차입니다. 테크니컬 라이터로 시작해서 2020년부터는 PM을 담당하고 있습니다. 자신의 이력을 모자로 표현한 일러스트가 인상적입니다. 테크니컬 라이터 경력은 약 15년이라고 합니다. (내부 문서 작성 및 배포 시스템 개발을 담당하고 있는 듯 한데 상용으로 공개된 제품인지 내부에서 쓰는 것인지 명확하지는 않습니다).
(Writerside라는 제품을 준비하고 있네요. 아직은 공개전이긴 합니다).
https://lp.jetbrains.com/writerside/
JetBrains은 다양한 언어와 기능을 지원하는 개발 도구를 만들고 있는데요. 각 개발도구는 공통적인 기능이 있고 특화된 기능이 있습니다. 12개의 개발 도구를 만든다면 문서 역시 12개가 나와야 합니다. 하지만 각 문서를 개별적으로 만드는 것이 아니고 공통 리소스를 만들고 이를 재사용하는 방식을 선택하고 있습니다. 때문에 JetBrains에는 20명의 테크니컬 라이터가 있는데 이들은 모두 같은 프로젝트에 참여합니다. 특정 1개의 개발 도구만 담당하는 것이 아니라는 거죠. 전체적인 시각을 가질 수 있는 장점도 있겠지만 문제가 생기면 다 같이 얽히게 되는 겁니다.
발표할 주제는 다음과 같습니다.
- 콘텐츠 재사용의 장점(Benefits of content reuse)
- 콘텐츠 재사용의 유형(Types of content reuse)
- 부작용(The flip side)
-- 재사용의 남용(Abuse of reuse)
-- 소스 코드 최소화(Source code reduction)
-- 재사용의 오용(Misuseof reuse)
-- 트래픽 자기 잠식(Traffic cannibalization)
그리고 각 부작용에 대해 단일 소스(single-source)의 장점을 잘 살리고 있는지 평가(sanity test)합니다.
- 일관성 유지(Maintain consistency)
- 중복된 업데이트 배제(Avoid makeing multiple updates)
- 리뷰, 편집 비용 감소(Reduce on the review/editing effort)
- 현지화 비용 감소(Reduce on localization costs)
- 반복 작업의 자동화(Automate the routine)
공통으로 사용하는 스니펫(콘텐츠)은 개발 도구, 버전에 따라 달라지는 부분을 변수로 처리했지만 스니펫 안에 스니펫이 들어가는 중첩 구조를 허용하고 있어서 시간이 지날수록 너무 복잡해지는 문제가 있었습니다.
재사용의 남용
모범적인 재사용은 제품에 따라 중요한 키워드나 스크린샷만 변수 등을 사용해 분기 처리하고 나머지 콘텐츠는 공통으로 사용할 수 있도록 작성하는 겁니다.
재사용의 남용은 비슷한 내용의 콘텐츠가 공통으로 작성되는 문제입니다. 이건 테크니컬 라이터의 책임도 큰데 기존에 작성된 내용보다 좀 더 잘 작성할 수 있다는 생각으로 새로운 것을 만들고 기존 것도 그대로 유지하는 것이죠. 이전 것을 교체하는 건 영향도를 확인해야 하니 그냥 새로 만드는 겁니다. 비슷한 내용의 중복도 문제지만 번역 비용의 증가로도 이어집니다.
sanity test는 0/5 점입니다.
어떻게 해결했나?
자체 스타일 가이드를 작성했습니다. 작가가 개인적인 취향이나 능력에 따라 내용을 작성하지 않고 정해진 가이드에 따라 작성합니다. 자동화된 도구(아마도 자체 편집기)에서 가이드의 내용을 따르고 있는지 확인해줍니다. 그리고 아직 완성은 아니지만 중복된 단락을 체크하는 도구도 만들고 있습니다.
소스 코드 최소화
JetBrains에서는 XML 기반으로 콘텐츠를 작성하는데 중첩된 Import와 필터가 적용되면서 특정 문제가 있는 문서를 찾는 것이 어려워지는 경우도 있습니다. 조직 특성상 코드처럼 문서를 작성하는데 이런 문화가 발목을 잡는 경우입니다.
sanity test는 3/5 점입니다.
리뷰, 편집이 어려워지고 자동화하는 루틴을 만들기가 어렵습니다.
어떻게 해결했나?
사용자 경험을 개선했습니다. 소스 코드가 좀 더 텍스트로 보이도록 했고 편집기에서 좀 더 쉽게 원하는 항목을 찾을 수 있도록 개선했습니다.
재사용의 오용
예시가 좀 애매한데 쓸데없는 단계가 하나 더 들어간 문제를 이야기하는 듯합니다.
실용주의 프로그래머 DRY 원칙 참조
https://johngrib.github.io/wiki/dry-principle/
sanity test는 2/5 점입니다.
업데이트 시 체크할 부분이 늘어나고 리뷰, 편집이 어려워지고 자동화하는 루틴을 만들기가 어렵습니다.
(이렇게 쓰고 보니 이 자체도 반복되는 부분이라 ㅠㅠ)
어떻게 해결했나?
DRY 원칙을 항상 지킬 수 없기에 Kiss 원칙을 도입했습니다.
콘텐츠 재사용이 목표가 아니라는 것을 인식했습니다.
https://johngrib.github.io/wiki/jargon/kiss-principle/
트래픽 자기 잠식
콘텐츠가 재사용되면서 같은 내용을 담고 있는 콘텐츠가 배포되면 검색 시 원하지 않은 제품의 콘텐츠가 노출될 수 있습니다.
어떻게 해결했나?
콘텐츠를 재사용하면 안된다?는 안되겠구요.
검색엔진이 콘텐츠와 관련된 정보를 인지할 수 있도록 메타 데이터를 추가하고 SEO 전문가의 조언을 받아 콘텐츠 게시 시기를 조정합니다. 그리고 탭 등을 사용해 비슷한 내용의 콘텐츠를 묶어주는 것도 좋습니다. 사용자 입장에서는 다른 링크를 타고 들어왔어도 원하는 탭을 금방 찾을 수 있으니깐요.
참조
https://blog.jetbrains.com/ru/team/2018/01/16/meet-anna-gasparyan-the-documentation-team-lead-for-intellij-idea/
Anna Gasparyan 인터뷰 기사입니다. 이제 막 콘텐츠 개선 작업을 시작했다는 걸 보면 이 즈음에 재사용 구조에 대한 개선 작업을 시작했었나 봅니다. 일상 루틴 중 StackOverflow에서 12개 정도의 태그를 항상 모니터링하고 사용자가 겪는 문제를 확인한다는 점이 인상적입니다.
Q&A를 진행한 것 같은데 아마도 영상 편집 과정에서 문제가 있었나 봅니다. 이 세션은 따로 Q&A 영상이 없네요.
영상
현장 스케치
Anna Gasparyan - Don't shoot yourself in the foot with content reuse
Explore writethedocs' photos on Flickr. writethedocs has uploaded 2645 photos to Flickr.
www.flickr.com
