개인적인 정리
놀랍게도 AWS에서 2020년까지는 문서 작업을 마이크로소프트 워드 기반으로 진행했다고 합니다(일부 팀만 그렇게 했다는 건지 아니면 AWS 전체를 이야기한 건지는 명확하지 않습니다. 하지만 발표자인 Marcia Riefer Johnston가 아마존에 합류한 것이 2019년이고 Integration & Automation 팀으로 옮긴 것이 2020년 3월이라 기존에 문서를 코드처럼 다루거나 자동화하는 프로세스가 없었을 수도 있습니다). 코드 기반으로 문서를 전환한 것은 2020년 중반에 시작한 일입니다.
* 개인적으로는 DOCS AS CODE가 정답이라고는 생각하지 않습니다. DOCS AS CODE의 장점을 살릴 수 있는 도구라면 대안으로 선택할 수도 있습니다. 특히 문서를 작성하는 팀이 문서팀 외 다양한 부서(기술지원, 교육 등)라면 좀 더 사용하기 쉬운 도구를 선택하는 것도 나쁘지 않습니다.
물론 깃허브에서 리뷰 프로세스 진행 시에 문서(코드)에 대한 직접적인 리뷰나 머지 등의 작업을 할 수 없다는 점은 아쉬울 수 있습니다.
워드 기반으로 작업하다 보니 협업 역시 이메일을 통해 작업하게 되고 작업된 문서를 다시 PDF로 생성해서 배포하는 수작업이 다수 포함되었습니다. 워드에서 PDF를 생성하는 과정에서도 간혹 오류가 발생하고 이를 해결하는 것도 쉬운 일은 아닙니다.
또한 개발팀에서 리눅스를 사용하는 개발자도 있는데 그들은 워드를 사용하지 않기 때문에 어려움이 있었고 서로 다른 버전의 워드를 사용하면서 데이터가 손실되는 일도 있었다고 합니다.
2020년 중반 워드를 버리고(?) AsciiDoc 기반으로 문서 작업을 이관합니다. 코드와 마찬가지로 깃허브에서 AsciiDoc 문서를 관리하고 리뷰, 배포 등의 프로세스도 코드처럼 운영하기 시작합니다.
하지만 이 과정에서도 문제는 있었다고 합니다. 코드와 문서가 같은 저장소 위치에 있다보니 오타 수정 같은 사소한 문서 작업 시에도 코드 전체를 테스트하고 빌드하는 작업이 진행되어 배포 프로세스에 상당히 부하가 되었다고 하네요.
또 문서에 포함되는 배포 옵션들이 있는데 그런 항목이 계속 늘어나면서 기존 문서에 대한 관리 부하가 늘어나는 문제가 있었습니다. 그래서 새로운 프로세스의 도입이 시급했다고 합니다. 그렇지 않으면 부채가 계속 늘어나는 식이니깐요.
깃허브에서는 문서 자체 브랜치를 분리하고 테스트, 배포를 위한 파이프라인을 분리했습니다.
참고
https://aws.amazon.com/ko/quickstart/
https://github.com/aws-quickstart/quickstart-documentation-base-common
https://github.com/aws-ia/aws-ia-documentation-base-common
Q&A
아. 올해 컨퍼런스에서는 Q&A를 두 개의 세션을 묶어서 진행했네요.
왜 이렇게 했는지는 모르겠으나~~ 그래서 같은 Q&A가 2개의 영상 뒤에 붙어 있습니다.
아마 의도는 같은 주제에 대해 각 발표자의 생각을 듣고자 한 것이 아닌가 싶은데 시간 관계 상 각자 질문은 각자 대답하는 방식이라 좀 애매한 상황이었습니다.
왜 마크다운 대신 AsciiDoc을 선택했나요?
음. 그냥 우리 조직에 적절하다고 판단되어서. 딱히 이유는 없다고 합니다.
영상
현장 스케치
Marcia Riefer Johnston and Dave May - One AWS team’s move to docs as code: what worked, what didn’t, what’s next
Explore writethedocs' photos on Flickr. writethedocs has uploaded 2645 photos to Flickr.
www.flickr.com
