이 페이지에는 Google Season of Docs에서 승인된 테크니컬 라이팅 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- CERN-HSF
- 테크니컬 라이터:
- 아리아드네
- 프로젝트 이름:
- Rucio – Rucio 문서 현대화 (재구성 및 재작성)
- 프로젝트 기간:
- 표준 기간 (3개월)
Project description
개요: Rucio 프레임워크는 이기종 데이터 센터 전반에 걸쳐 지리적으로 분산된 대량의 과학 데이터를 관리하고 구성할 수 있는 관점으로 개발되었습니다. 분산 데이터 복구 및 적응형 복제와 같은 기능을 제공하는 이 프레임워크는 확장성, 모듈식, 확장성이 뛰어납니다. 이러한 서비스를 위해 문서 소비자는 다양한 배경을 가지고 있으며 액세스할 때 다양한 요구 사항이 있습니다. 따라서 이러한 서비스에 대한 좋은 문서는 최종 사용자를 위한 채택 및 활용을 간소화하는 동시에 일반적인 문제 및 문제 해결을 위한 참조로 활용해야 합니다.
이러한 문서가 없다면 효율적이고 효과적으로 활용하는 데 중대한 장애가 될 수 있습니다. 이로 인해 지원 비용이 증가하고 제품의 기업 정체성에 대한 평판에 위험을 초래할 수 있습니다. 결국 문서는 커뮤니케이션 수단입니다. 따라서 커뮤니케이션이 관리 가능하고 액세스 가능한 프레임워크에 캡슐화되어 적절한 버전 관리와 관련성을 유지할 수 있어야 합니다.
이 글을 작성하는 시점에서 ATLAS의 고에너지 요구사항과 LHC의 CMS 실험을 지원하는 데 Rucio 프레임워크가 활용되었습니다. 또한 천체 물리학과 같이 LHC를 넘어 다양한 과학계의 니즈를 충족하기 위해 사용되고 있기 때문에 가능한 한 관련성이 높고 접근 가능한 문서가 되어야 합니다. 이 프로젝트를 통해 CERN은 Rucio의 최종 사용자가 모든 관련 문서에 액세스할 수 있는 중앙 집중식 뷰를 제공하여 프레임워크를 활용하면서 원활한 환경을 경험할 수 있도록 하고자 합니다.
현재 상태: 현재 사용자 문서는 다양한 위치에 분산되어 있으며 과학 논문, 코드의 소스가 있는 readthedocs.io, Google Drive, GitHub, DockerHub, Wikis 등 다양한 형식으로 되어 있습니다. 여러 소스에서 버전 추적 및 문서의 정확성과 관련된 문제가 발생합니다. 또한 분산된 문서 모델은 특정 사용 사례의 관련 정보를 탐색하고 표시하는 데 있어 심각한 장애물이 됩니다. 특히 Wikis의 경우 특정 실험에 제공된 정보는 동일하거나 다른 소스에 위치한 다른 인스턴스에도 매우 잘 적용될 수 있습니다. 그러나 통합 및 적절한 연결이 부족하여 이 정보가 휴면 상태로 유지되며 잠재적으로 활용도가 떨어질 수 있습니다.
제안된 사용자 문서가 현재 문서보다 개선된 이유는 무엇입니까? 다면적인 문제를 고려하여 아래 제안된 모델은 아래에 설명된 대로 문서의 탐색, 버전 관리, 추적, 표시와 관련된 장애물을 제거합니다.
이 문서의 재구성은 최종 사용자를 탐색하는 데 소요되는 작업을 간소화하기 위한 것입니다. 정보를 검색하는 동안 토끼 굴에 내려갈 필요가 없습니다. 단순성을 위해 분류/라벨이 지정되기 때문입니다. 재구성을 통해 요구사항을 기반으로 자유롭게 분류할 수 있으므로 관리 관점에서도 버전 관리 및 추적이 간편해집니다. 재구성된 모든 문서를 중앙 집중화하면 여러 소스를 참조하지 않고도 모든 정보가 사용자에게 표시되도록 할 수 있습니다.
분석: 요건 브리핑을 읽고 멘토링팀과 대화를 나눈 결과, Rucio 문서의 현재 상태에 대한 공제액은 다음과 같습니다.
문서의 주요 출처는 6가지입니다. - Google Drive 링크: https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
코드에 소스가 있는 Sphinx로 구동되는 문서를 읽습니다. 코드 링크: https://github.com/rucio/rucio ReadtheDocs 링크: https://rucio.readthedocs.io/en/latest/
DockerHub 링크: https://hub.docker.com/u/rucio
GitHub 링크: https://github.com/rucio/rucio
Wikis 링크: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
과학 자료 링크: https://arxiv.org/abs/1902.09857
이러한 소스의 문서는 서로 다른 형식으로 되어 있습니다. 예를 들어 Google Drive에는 Slides 및 Docs 형식의 문서가 있으며 GitHub에는 주로 reStructuredText 마크업 언어 등으로 된 파일이 있습니다. 버전 관리 및 추적이 부족하여 여러 소스에 중복 정보가 게시될 수 있습니다. 정보의 라벨 지정/분류에 일관성이 없습니다. 따라서 검색에는 이전 경험과 전문 지식이 필요합니다.
무수한 형식과 소스를 고려할 때 기대는 정보를 재구성하고 mkdocs를 사용해 중앙화하는 것입니다. 도구에 대해 더 잘 이해할 수 있도록 도구 사용법을 조사하고 익혔습니다.
결과: 기존 문서가 구조화되지 않았으며 적절한 연결 없이 흩어져 있습니다. 또한 중앙 집중화와 형식의 일관성이 부족합니다. 이로 인해 사용자는 검색에 추가 노력을 기울여야 합니다. 이러한 격차는 또한 관리자/유지관리 담당자/리드에게 불필요한 부담을 초래하며, 이로 인해 문서 유지 관리 및 문서 업데이트를 위한 커뮤니티 중심의 접근 방식을 유지하기가 어려워집니다. 사용자 및 참여자 환경이 크게 저하되며 반복됩니다.
제안된 문서의 구조:
요구사항을 철저히 분석한 후 재구성된 문서 모델을 통해 주요 고충을 해결하기로 결정했습니다.
재구성된 모델은 아래 첨부된 모형에서 시연되며 모든 문서가 아래 7가지 카테고리로 분류됩니다.
- 정보
- 시작하기
- 개념
- Rucio 인터페이스
- 작업
- 튜토리얼
- 고급 노하우
물론 이 프로그램을 수료한 후 링크 추가와 같은 개선 사항도 있습니다. Rucio에서 1,000명이 넘는 활성 사용자가 500페타바이트의 데이터에 액세스하고 있는 상황에서, 문서 재구성 제안으로 사용자가 지원 메일링 리스트에 의존할 필요성을 크게 줄일 수 있을 것입니다. 목표는 클릭률을 낮추고 분류 및 라벨 지정을 통해 문서를 쉽게 표시하여 사용자 경험을 개선하는 것입니다. 사용자/운영/관리자의 관점에서 알아야 하는 모든 것을 클릭 3회 이내에 사용할 수 있습니다.
예시 링크: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)
프로젝트 목표: - 다양한 소스에서 제공되는 중복 정보를 분석하고 정리합니다. 즉, 모든 정보가 하나의 정보 소스를 가져야 합니다. - 기존 문서의 라벨을 지정하고 여러 부분으로 분류하여 재구성 - 재구성된 문서를 mkdocs 기반의 중앙 집중식 뷰로 이전 - 파일 형식 제약으로 인해 이전할 수 없는 문서의 형식 지정/가져오기 - 링크, 정보 업데이트, 오류 수정 등 누락된 부분을 메우기 위해 커뮤니티 중심의 문서 수정을 설정합니다.
이 시스템의 기본 틀은 이미 마련되었지만 이 모델은 적절한 문서화와 함께 기여 및 거버넌스에 대한 적절한 가이드라인을 마련하여 기존 시스템을 개선할 것입니다. 또한 프로젝트의 문제 및 전반적인 상태를 추적하기 위해 GitHub 프로젝트 보드를 통합할 계획입니다.
타임라인: - 8월 16일 이전 --> 최신 버전의 문서 및 Rucio 숙지 --> 프로젝트 기간 중 도움이 될 새로운 기술 및 기술 글쓰기 기술 학습 --> GitHub에 보고된 문서 문제(있는 경우)에 참여
커뮤니티 유대감 (8월 17일~9월 13일) --> 시간대의 차이를 반영하기 위한 커뮤니케이션 채널 및 시간 마련 (푸네는 3시간 30분 늦음) --> 목표 개선 과정에서 확인해야 할 주요 고충 --> 대화를 통해 커뮤니티, 조직, 프레임워크에 대해 자세히 알아봅니다. --> 멘토 및 조직의 주요 구성원과 함께 제안된 문서 구조를 평가하여 구현 가능성 및 실현 가능성을 평가합니다. --> 제안된 기능 및 기존 문서에 적용해야 할 기타 수정 사항 완료.
문서화 기간 (9월 14일~11월 30일) 제가 여기에서 만든 제안된 형식을 기반으로 문서화 기간 동안 달성하고자 하는 주요 마일스톤에 대한 세부정보를 제공했습니다.
--> 마일스톤 #1: 분류 및 라벨 지정 ETC: 2020년 9월 28일 사용 가능한 문서를 수집하고 라벨을 지정하면 재구성 및 정리 프로세스가 크게 간소화됩니다.
--> 마일스톤 #2: 분석, 정리, 재구성 ETC: 2020년 10월 19일 마일스톤 1에서 분류된 문서는 중복 및 중복 정보 소스를 분석하는 데 사용됩니다. 프로젝트 정보에 명시된 바와 같이 Google은 사용 가능한 모든 정보의 단일 정보 소스를 대상으로 합니다.
--> 마일스톤 #3: 중앙 집중화 및 형식 변경: ETC: 2020년 11월 9일 문서를 다듬고 재구성했다면 먼저 형식을 다시 지정해 보겠습니다. 소스가 다양하므로 형식이 다르기 때문에 먼저 적절한 형식으로 변환해야 합니다. 이 작업이 완료되면 중앙 집중화 프로세스가 더 쉬워집니다.
--> 주요 일정 4: 관리/참여 관련 추적 위원회 및 문서 설정 ETC: 2020년 11월 23일 이 단계는 프로젝트 완료 후에도 문서가 계속 업데이트되도록 하기 위한 것입니다. 가이드라인을 마련하고 프로젝트 위원회를 구성하면 커뮤니티 공약을 요청하고 이를 효과적으로 추적하는 행정부의 부담을 덜어줄 수 있습니다.
--> 프로젝트 평가 (11월 30일~12월 5일) 프로젝트 보고서 및 멘토 평가 제출 학생의 Season of Docs에 대한 내 경험 보고서를 작성하여 제출합니다.
이 프로젝트가 필요한 이유 잘 작성되고 버전이 지정된 문서로 코드를 보완하는 것이 채택을 확대하고 더 효과적으로 사용할 수 있는 유일한 방법이라고 생각합니다. 개인적으로 저는 CERN이 다양한 물리학 분야에서 최첨단 연구를 선도해 온 방식에 매료되었습니다. 이러한 실험 중에 처리, 전송, 생성되는 정보의 규모를 고려할 때 저는 조직 내에서 데이터를 참조용으로 관리하는 방법과 향후 사용을 위해 어떻게 관리하는지 궁금했습니다. 몇몇 놀라운 과학 연구 및 발견의 원동력이 되어 온 프레임워크의 문서화를 개선하는 데 기여하게 되어 영광입니다.
내가 이 프로젝트에 적합한 담당자인 이유는 무엇인가요? 기본 요건을 충족해야 할 뿐만 아니라 다음과 같은 이유로 이 프로젝트에 적합한 업무 담당자가 될 것이라고 확신합니다.
저는 이미 Kubernetes의 기존 문서를 수정하는 작업을 하고 있습니다. 이러한 기여로 인해 Kubernetes 1.19 출시 주기의 출시 문서 그림자로 포함되었고, 출시 중에 추가되는 새로운 기능에 대한 문서를 효과적으로 유지관리하고 업그레이드하는 데 기여했습니다. 양질의 문서는 우수한 제품/서비스의 근간이 된다고 생각합니다. 절차적이든 기술적이든 간에 잘 작성되고 간결하며 쉽게 액세스할 수 있는 정보는 도입을 촉진하고 더 나은 사용을 도모하는 원동력이 될 수 있습니다. 경력 전반에 걸쳐 데이터 기반 분산 시스템과 작업하면서 이러한 시스템의 문서화와 관련된 요구사항의 복잡성을 이해할 수 있는 가장 좋은 위치에 있다고 생각합니다. 저도 최종 사용자였기 때문에 잘못 작성되었거나 부정확한 문서의 함정에 대해 잘 알고 있기 때문에 재구성 과정에서 이러한 부분을 고려하도록 주의를 기울여야 합니다.