이 페이지에는 Google Season of Docs에 선정된 기술 문서 프로젝트의 세부정보가 포함되어 있습니다.
프로젝트 요약
- 오픈소스 조직:
- CERN-HSF
- 기술 문서 작성자:
- Ariadne
- 프로젝트 이름:
- Rucio – Rucio 문서 현대화 (구조 조정 및 재작성)
- 프로젝트 길이:
- 표준 기간 (3개월)
Project description
개요: Rucio 프레임워크는 이질적인 데이터 센터에 지리적으로 분산된 대규모 과학 데이터를 관리하고 구성하기 위해 개발되었습니다. 이 프레임워크는 분산 데이터 복구 및 적응형 복제와 같은 기능을 제공하며 확장성이 뛰어난 모듈식입니다. 이러한 서비스의 문서를 사용하는 사용자는 다양한 배경을 가지고 있으며 문서에 액세스할 때 다양한 요구사항이 있습니다. 따라서 이러한 서비스에 대한 좋은 문서는 최종 사용자의 서비스 채택 및 활용을 간소화하는 동시에 일반적인 문제 및 문제 해결에 대한 참고 자료가 되어야 합니다.
이러한 문서가 없으면 효율적이고 효과적인 활용에 상당한 장애가 발생합니다. 이로 인해 지원 비용이 증가하고 제품의 기업 이미지에 대한 평판 위험이 발생할 수 있습니다. 결국 문서는 커뮤니케이션의 한 가지 방식입니다. 따라서 적절한 버전 관리와 관련성을 유지하면서 관리 가능하고 액세스 가능한 프레임워크에 커뮤니케이션을 캡슐화하는 것이 성공적인 커뮤니케이션을 보장하는 것입니다.
이 문서를 작성하는 현재 Rucio 프레임워크는 ATLAS와 LHC에서 진행되는 CMS 실험의 고에너지 요구사항을 구동하는 데 활용되었습니다. 또한 천체물리학과 같은 LHC 외의 다양한 과학 커뮤니티의 요구를 지원하는 데 사용되므로 가능한 한 관련성이 높고 접근 가능한 문서가 필요합니다. CERN은 이 프로젝트를 통해 Rucio의 최종 사용자가 모든 관련 문서에 액세스할 수 있는 중앙 집중식 뷰를 제공하여 프레임워크를 활용하면서 원활한 환경을 제공하고자 합니다.
현재 상태: 현재 사용자 문서는 여러 위치에 흩어져 있으며 과학 논문, 코드에 소스가 포함된 readthedocs.io, Google Drive, GitHub, DockerHub, 위키 등 다양한 형식으로 제공됩니다. 소스가 다양하면 문서의 버전 추적과 정확성에 문제가 생길 수 있습니다. 또한 문서화의 분산 모델은 특정 사용 사례에 관한 관련 정보를 탐색하고 표시하는 데 상당한 장애가 됩니다. 특히 위키의 경우 특정 실험에 제공된 정보가 동일한 소스 또는 다른 소스에 있는 다른 인스턴스에도 적용될 수 있습니다. 그러나 통합 및 적절한 연결이 부족하여 이러한 정보는 비활성 상태로 있으며 잠재적으로 활용도가 낮을 수 있습니다.
제안된 사용자 문서가 현재 문서보다 개선된 이유는 무엇인가요? 다면적인 문제를 감안할 때, 아래 제안된 모델은 아래의 설명과 같이 문서의 탐색, 버전 관리, 추적 및 표시와 관련된 장애물을 제거합니다.
문서를 재구성하는 목적은 최종 사용자가 탐색하는 데 드는 노력을 간소화하는 것입니다. 정보가 간편하게 분류/라벨이 지정되므로 정보를 검색하는 동안 깊이 들어가지 않아도 됩니다. 재구성하면 요구사항에 따라 자유롭게 분류할 수 있으므로 관리 측면에서 버전 관리 및 추적이 쉬워집니다. 구조 조정된 모든 문서를 중앙 집중화하면 사용자가 여러 소스를 참조하지 않고도 모든 정보를 볼 수 있습니다.
분석: 요구사항 개요를 검토하고 멘토링팀과 대화를 나눈 결과, Rucio 문서의 현재 상태에 대한 추론은 다음과 같습니다.
문서 소스는 크게 6가지가 있습니다. - Google Drive 링크: https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7
Readthedocs(코드에 소스 포함) 코드 링크: 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
위키 링크: 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에서 500페타바이트의 데이터에 액세스하는 활성 사용자 수가 1, 000명을 넘기 때문에 문서를 재구성하면 사용자가 지원 메일링 목록에 의존할 필요가 크게 줄어들 것입니다. 목표는 클릭률을 낮추고 분류 및 라벨 지정을 통해 문서를 쉽게 표시하여 사용자 환경을 개선하는 것입니다. 사용자/운영/관리자 관점에서 알아야 할 모든 정보는 클릭 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: 분석, 정리, 재구성 등: 2020년 10월 19일 마일스톤 1에서 분류된 문서를 중복 및 중복된 정보 소스로 분석합니다. 프로젝트 정보에 명시된 대로 Google은 사용 가능한 모든 정보에 대해 하나의 정보 소스를 타겟팅하고 있습니다.
--> 마일스톤 3: 중앙 집중화 및 형식 지정 변경: ETC: 2020년 11월 9일 문서가 적절하게 정리되고 재구성되면 먼저 형식을 변경하는 것을 목표로 합니다. 소스가 다양하기 때문에 형식이 다르며 먼저 적절한 형식으로 변환해야 합니다. 이렇게 하면 중앙 집중화 프로세스가 더 쉬워집니다.
--> 마일스톤 4: 추적 보드 설정 + 거버넌스/참여에 관한 문서 등: 2020년 11월 23일 이 단계는 프로젝트 완료 후에도 문서가 계속 업데이트되도록 하는 것입니다. 지침을 세우고 프로젝트 이사회를 마련하면 행정 구성원이 커뮤니티 기여를 요청하고 이를 효과적으로 추적해야 하는 부담을 덜 수 있습니다.
--> 프로젝트 평가 (11월 30일~12월 5일) 프로젝트 보고서 및 멘토 평가 제출 시즌 오브 문서 참가자로서 겪은 경험에 관한 보고서 작성 및 제출
이 프로젝트를 선택한 이유는 무엇인가요? 코드를 잘 작성되고 버전이 지정된 문서로 보완하는 것이 더 많은 채택과 더 나은 사용을 가능하게 하는 유일한 방법이라고 생각했습니다. 저는 개인적으로 CERN이 물리학의 다양한 분야에서 최첨단 연구를 선도해 온 방식에 매료되었습니다. 이러한 실험 중에 처리, 전송, 생성되는 정보의 규모를 감안할 때 조직 내에서 참조 및 향후 사용을 위해 데이터가 어떻게 관리되는지 항상 궁금했습니다. 놀라운 과학적 연구와 발견을 지원해 온 프레임워크의 문서를 개선하는 데 기여할 수 있어 기쁩니다.
이 프로젝트에 적합한 이유 기본 요건을 충족할 뿐만 아니라 다음과 같은 이유로 이 프로젝트에 적합한 인재라고 생각합니다.
이미 Kubernetes의 기존 문서를 수정하는 작업을 진행하고 있습니다. 이러한 기여로 인해 1.19 Kubernetes 출시 주기에 관한 출시 문서 섀도로 등록되어 출시 중에 추가되는 새 기능에 관한 문서를 효과적으로 유지 관리하고 업그레이드하는 데 기여하고 있습니다. 좋은 문서는 훌륭한 제품/서비스의 근간이라고 생각합니다. 절차적이든 기술적인이든, 잘 작성되고 간결하며 쉽게 액세스할 수 있는 정보는 채택을 촉진하고 더 나은 사용을 촉진하는 데 동기가 됩니다. 저는 커리어 전반에서 데이터 기반 분산 시스템을 다뤄 왔기 때문에 이러한 시스템의 문서와 관련된 요구사항의 복잡성을 가장 잘 이해할 수 있다고 생각합니다. 저도 최종 사용자였기 때문에 작성 상태가 좋지 않거나 잘못된 문서의 함정에 대해 잘 알고 있으며, 구조 조정 과정에서 이러한 점을 고려하도록 주의하겠습니다.