Dự án CERN-HSF

Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần tài liệu của Google.

Tóm tắt dự án

Tổ chức nguồn mở:
CERN-HSF
Người viết nội dung kỹ thuật:
Ariadne
Tên dự án:
Rucio – Hiện đại hoá (tái cấu trúc và viết lại) tài liệu của Rucio
Thời lượng dự án:
Thời gian tiêu chuẩn (3 tháng)

Mô tả dự án

Tóm tắt: Khung Rucio được phát triển nhằm mục đích quản lý và sắp xếp lượng lớn dữ liệu khoa học được phân bổ theo khu vực địa lý trên các trung tâm dữ liệu không đồng nhất. Cung cấp các tính năng như khôi phục dữ liệu phân tán và sao chép thích ứng, khung này có khả năng mở rộng, mô-đun và có thể mở rộng cao. Người tiêu dùng tài liệu cho một dịch vụ như vậy sẽ xuất thân từ nhiều hoàn cảnh xuất thân và có các yêu cầu khác nhau khi sử dụng dịch vụ này. Do đó, tài liệu tốt cho một dịch vụ như vậy phải đơn giản hoá việc sử dụng và áp dụng dịch vụ đó cho người dùng cuối, đồng thời là tài liệu tham khảo cho các vấn đề thường gặp và cách khắc phục sự cố.

Nếu không có tài liệu như vậy, bạn sẽ gặp phải những trở ngại đáng kể trong việc sử dụng hiệu quả và hiệu quả. Điều này có thể làm tăng chi phí hỗ trợ và gây rủi ro về danh tiếng cho bản sắc doanh nghiệp của sản phẩm. Xét cho cùng, tài liệu là một phương thức giao tiếp. Do đó, việc đảm bảo rằng thông tin liên lạc được đóng gói trong một khung có thể quản lý và truy cập được, đồng thời vẫn phù hợp với phiên bản thích hợp là cách để đảm bảo chúng ta đang giao tiếp để đạt được thành công.

Tại thời điểm viết bài này, khung Rucio đã được sử dụng để đáp ứng các yêu cầu năng lượng cao của các thử nghiệm ATLAS và CMS tại LHC. Dữ liệu này cũng được sử dụng để hỗ trợ nhu cầu của các cộng đồng khoa học đa dạng ngoài LHC, chẳng hạn như vật lý thiên văn; do đó khiến tài liệu trở nên phù hợp và dễ tiếp cận nhất có thể. Với sự trợ giúp của dự án này, CERN muốn người dùng cuối của Rucio có trải nghiệm liền mạch trong khi sử dụng khung bằng cách cung cấp chế độ xem tập trung để truy cập vào tất cả tài liệu liên quan.

Trạng thái hiện tại: Kể từ hôm nay, tài liệu người dùng được phân bổ ở nhiều nơi và ở nhiều định dạng, bao gồm cả các bài báo khoa học, readthedocs.io có nguồn trong mã, Google Drive, GitHub, DockerHub hoặc Wiki. Việc có nhiều nguồn dẫn đến các vấn đề về việc theo dõi phiên bản và tính chính xác của tài liệu. Ngoài ra, mô hình tài liệu phi tập trung cũng đặt ra những trở ngại đáng kể trong việc điều hướng và hiển thị thông tin liên quan cho một trường hợp sử dụng nhất định. Đặc biệt trong trường hợp Wiki, thông tin được cung cấp cho một thử nghiệm cụ thể có thể rất phù hợp với các thực thể khác nằm trong cùng/các nguồn khác. Tuy nhiên, do thiếu sự hợp nhất và các mối liên kết thích hợp nên thông tin này không hoạt động và có khả năng chưa được sử dụng đúng mức.

Tại sao tài liệu người dùng mà bạn đề xuất là một điểm cải tiến so với tài liệu hiện tại? Do vấn đề đa diện này, mô hình được đề xuất dưới đây sẽ loại bỏ các trở ngại khi điều hướng, tạo phiên bản, theo dõi và hiển thị tài liệu như chi tiết dưới đây:

Việc tái cấu trúc tài liệu nhằm đơn giản hoá nỗ lực của người dùng cuối trong việc điều hướng. Người dùng không cần phải tìm kiếm thông tin theo cách rườm rà vì thông tin sẽ được phân loại/gắn nhãn để đơn giản hoá. Từ góc độ quản trị, việc tạo phiên bản và theo dõi sẽ trở nên dễ dàng vì việc tái cấu trúc sẽ cho phép bạn tự do phân loại dựa trên yêu cầu. Việc tập trung tất cả tài liệu được tái cấu trúc sẽ giúp đảm bảo người dùng có thể xem tất cả thông tin mà không cần tham khảo nhiều nguồn.

Phân tích: Sau khi đọc qua bản tóm tắt yêu cầu và trò chuyện với nhóm cố vấn, tôi đã suy luận về trạng thái hiện tại của tài liệu Rucio như sau:

Có 6 nguồn tài liệu chính: - Đường liên kết đến Google Drive : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7

  • Readthedocs do Sphinx cung cấp nguồn trong mã Đường liên kết đến Mã: https://github.com/rucio/rucio Đường liên kết đến ReadtheDocs: https://rucio.readthedocs.io/en/latest/

  • DockerHub Đường liên kết: https://hub.docker.com/u/rucio

  • Đường liên kết GitHub: https://github.com/rucio/rucio

  • Wiki Đường liên kết: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing

  • Bài viết khoa học Đường liên kết: https://arxiv.org/abs/1902.09857

Tài liệu trên các nguồn này có nhiều định dạng. Ví dụ: Google Drive có tài liệu ở dạng Trang trình bày và Tài liệu, GitHub có các tệp chủ yếu ở ngôn ngữ đánh dấu reStructuredText, v.v. Việc thiếu tính năng theo dõi và tạo phiên bản dẫn đến việc xuất bản thông tin thừa trên nhiều nguồn. Không có sự thống nhất trong việc gắn nhãn/phân loại thông tin. Do đó, bạn cần có kinh nghiệm và kiến thức chuyên môn trước đó khi tìm kiếm.

Do có vô số định dạng và nguồn, nên bạn cần phải tái cấu trúc và tập trung thông tin bằng mkdocs. Để hiểu rõ hơn về các công cụ này, tôi đã nghiên cứu và làm quen với cách sử dụng các công cụ đó.

Kết quả: Tài liệu hiện có không có cấu trúc và bị phân tán mà không có đường liên kết thích hợp. Mã nguồn này cũng thiếu tính tập trung và tính đồng nhất trong định dạng. Điều này khiến người dùng phải tốn thêm công sức để tìm kiếm. Những khoảng trống như vậy cũng gây áp lực không cần thiết cho quản trị viên/người bảo trì/người phụ trách, khiến việc duy trì phương pháp do cộng đồng dẫn dắt để bảo trì và cập nhật tài liệu trở nên khó khăn. Trải nghiệm của người dùng và người đóng góp bị giảm sút đáng kể và sẽ có

Cấu trúc cho tài liệu đề xuất: Sau khi phân tích kỹ lưỡng các yêu cầu, tôi quyết định giải quyết các vấn đề chính thông qua mô hình tài liệu được cấu trúc lại.
Mô hình được tái cấu trúc được minh hoạ trên bản mô phỏng đính kèm bên dưới và sẽ phân loại mọi tài liệu thành 7 danh mục dưới đây:

  • Giới thiệu
  • Bắt đầu
  • Khái niệm
  • Giao diện Rucio
  • Tasks
  • Hướng dẫn
  • Kiến thức nâng cao

Tất nhiên, tôi vẫn còn một số điểm cần cải thiện, chẳng hạn như thêm đường liên kết sau khi hoàn thành chương trình này. Với hơn 1.000 người dùng đang hoạt động truy cập vào 500 petabyte dữ liệu trên Rucio, việc tái cấu trúc tài liệu được đề xuất có thể giúp giảm đáng kể nhu cầu người dùng phải sử dụng danh sách gửi thư hỗ trợ. Mục tiêu là cải thiện trải nghiệm người dùng bằng cách giảm số lượt nhấp và dễ dàng hiển thị tài liệu thông qua việc phân loại và gắn nhãn. Mọi thông tin cần biết từ góc độ nhân viên của người dùng/vận hành/quản trị viên sẽ có sẵn trong vòng tối đa 3 lượt nhấp.

Đường liên kết đến bản minh hoạ: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

Mục tiêu của dự án: – Phân tích và loại bỏ thông tin thừa có sẵn từ nhiều nguồn. Tức là mỗi thông tin phải có một nguồn đáng tin cậy. – Tái cấu trúc bằng cách gắn nhãn và phân loại tài liệu hiện có thành nhiều phần – Di chuyển tài liệu được tái cấu trúc sang chế độ xem tập trung dựa trên mkdocs – Định dạng lại/nhập tài liệu không thể di chuyển do các quy tắc hạn chế về định dạng tệp – Thiết lập việc sửa đổi tài liệu do cộng đồng điều khiển để đảm bảo mọi khoảng trống bị thiếu đều được lấp đầy – về các mối liên kết, nội dung cập nhật hoặc sửa lỗi.

Tuy nhiên, điểm cốt lõi của hệ thống này đã được thiết lập sẵn, mô hình của tôi sẽ cải thiện dựa trên hệ thống hiện có bằng cách đặt ra các nguyên tắc phù hợp cho việc đóng góp và quản trị cùng với tài liệu phù hợp. Hơn nữa, tôi dự định kết hợp các bảng dự án GitHub để theo dõi các vấn đề và tình trạng tổng thể của dự án.

Tiến trình: - Trước ngày 16 tháng 8 --> Làm quen với các phiên bản tài liệu và Rucio hiện tại --> Tìm hiểu các kỹ thuật mới và kỹ năng viết kỹ thuật sẽ hữu ích trong thời gian thực hiện dự án --> Đóng góp cho các vấn đề về tài liệu (nếu có) được báo cáo trên GitHub

  • Gắn kết cộng đồng (17/8 – 13/9) --> Thiết lập kênh giao tiếp và thời gian để tính đến sự chênh lệch múi giờ (Pune sẽ sớm được xác định trước 3 giờ 30 phút) --> Các vấn đề chính cần xác định nhằm tinh chỉnh mục tiêu --> Tìm hiểu thêm về cộng đồng, tổ chức và khung làm việc bằng cách tương tác trong các cuộc trò chuyện. --> Đánh giá cấu trúc tài liệu đề xuất với các cố vấn và các thành viên chính khác của tổ chức để xác định khả năng tồn tại và khả năng triển khai. --> Hoàn tất các tính năng được đề xuất và mọi nội dung sửa đổi khác có thể cần thực hiện đối với tài liệu hiện có.

  • Thời gian lập tài liệu (14 tháng 9 – 30 tháng 11) Dựa trên định dạng đề xuất mà tôi đã đề xuất tại đây, tôi đã cung cấp thông tin chi tiết về các mốc quan trọng mà tôi dự định đạt được trong thời gian lập tài liệu.

--> Cột mốc #1: Phân loại và gắn nhãn ETC: Ngày 28 tháng 9 năm 2020 Việc tổng hợp tài liệu hiện có và gắn nhãn cho các tài liệu đó sẽ giúp đơn giản hoá đáng kể quá trình tái cấu trúc và cắt giảm.

--> Mốc #2: Phân tích, loại bỏ và tái cấu trúc ETC: Ngày 19 tháng 10 năm 2020 Tài liệu đã được phân loại trong Mốc #1 sẽ được phân tích để tìm các nguồn thông tin trùng lặp và thừa. Như đã nêu trong thông tin dự án, chúng tôi đang nhắm đến một nguồn đáng tin cậy cho tất cả thông tin có sẵn.

--> Cột mốc #3: Tập trung và định dạng lại: ETC: Ngày 9 tháng 11 năm 2020 Sau khi đã cắt bớt và tái cấu trúc tài liệu đúng cách, trước tiên, tôi sẽ định dạng lại tài liệu. Do có nhiều nguồn, các định dạng cũng khác nhau và trước tiên cần được chuyển đổi thành một định dạng thích hợp. Sau khi hoàn tất, quá trình tập trung sẽ trở nên dễ dàng hơn.

--> Cột mốc số 4: Thành lập ban theo dõi + tài liệu về hoạt động quản trị/khoản đóng góp ETC: Ngày 23 tháng 11 năm 2020 Giai đoạn này nhằm đảm bảo rằng sau khi dự án hoàn tất, tài liệu sẽ tiếp tục được cập nhật. Việc đặt ra nguyên tắc và thiết lập bảng điều khiển dự án sẽ giúp các thành viên quản trị giảm bớt gánh nặng trong việc thu hút nội dung đóng góp của cộng đồng và theo dõi nội dung đó một cách hiệu quả.

--> Đánh giá dự án (30/11 đến 5/12) Gửi báo cáo dự án và đánh giá của cố vấn Viết và gửi báo cáo về trải nghiệm của mình với tư cách là người tham gia trong Mùa Tài liệu.

Tại sao lại chọn dự án này? Tôi tin rằng việc bổ sung mã bằng tài liệu được viết cẩn thận và có phiên bản là cách duy nhất để giúp mọi người sử dụng rộng rãi hơn và hiệu quả hơn. Cá nhân tôi rất ấn tượng với cách CERN tiên phong trong nghiên cứu tiên tiến ở nhiều lĩnh vực Vật lý. Do quy mô thông tin được xử lý, chuyển và tạo ra trong các thử nghiệm như vậy, tôi luôn tò mò về cách quản lý dữ liệu để tham khảo và sử dụng trong tương lai trong tổ chức. Tôi rất vinh dự được đóng góp vào việc cải thiện tài liệu cho một khung đã hỗ trợ một số nghiên cứu và khám phá khoa học tuyệt vời.

Tại sao tôi là người phù hợp cho dự án này? Ngoài việc đáp ứng các điều kiện tiên quyết, tôi tự tin mình sẽ là người phù hợp cho dự án này vì:

Tôi đang nỗ lực sửa đổi tài liệu hiện có cho Kubernetes. Những đóng góp này đã giúp tôi được liệt kê là Người hỗ trợ tài liệu phát hành cho chu kỳ phát hành Kubernetes 1.19, trong đó tôi đóng góp vào việc duy trì và nâng cấp tài liệu một cách hiệu quả cho các tính năng mới được thêm vào trong các bản phát hành. Tôi tin rằng tài liệu chất lượng cao là nền tảng cho một sản phẩm/dịch vụ chất lượng cao. Dù là thông tin quy trình hay kỹ thuật, thông tin được viết rõ ràng, súc tích và dễ truy cập sẽ là động lực thúc đẩy việc sử dụng và giúp sử dụng hiệu quả hơn. Suốt sự nghiệp làm việc với các hệ thống phân phối dựa trên dữ liệu, tôi tin rằng mình sẽ là người phù hợp nhất để hiểu rõ những điểm phức tạp trong các yêu cầu liên quan đến việc tài liệu hoá các hệ thống này. Bản thân tôi cũng là một người dùng cuối, nên tôi hiểu rõ những cạm bẫy của tài liệu được viết không tốt/không chính xác và sẽ cẩn thận cân nhắc những vấn đề đó trong quá trình tái cấu trúc.