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 Google Tài liệu.

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 về 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 một lượng lớn dữ liệu khoa học được phân phối theo địa lý trên các trung tâm dữ liệu không đồng nhất. Cung cấp các chức năng như khôi phục dữ liệu phân phối và nhân bản sao chép thích ứng, khung này có khả năng mở rộng, mô-đun và mở rộng với tốc độ cao. Những người sử dụng tài liệu liên quan đến một dịch vụ như vậy sẽ có xuất thân khác nhau và có các yêu cầu khác nhau khi sử dụng tài liệu đó. Do đó, tài liệu hữu ích về dịch vụ đó cần phải đơn giản hoá quá trình nhận và sử dụng 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ó những tài liệu như vậy, thì việc sử dụng hiệu quả và hiệu quả sẽ gây ra những trở ngại đáng kể. Điều này có thể làm tăng chi phí hỗ trợ và gây rủi ro về uy tín đối với danh tính doanh nghiệp của sản phẩm. Suy cho cùng thì tài liệu cũng là một phương thức giao tiếp. Việc giao tiếp được gói gọn trong một khung làm việc dễ quản lý và dễ tiếp cận mà vẫn phù hợp với việc tạo phiên bản phù hợp. Điều này giúp đảm bảo chúng ta giao tiếp 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. Nó cũng đang được sử dụng để hỗ trợ nhu cầu của các cộng đồng khoa học đa dạng ngoài ngành vật lý thiên văn, chẳng hạn như vật lý thiên văn; do đó, cần phải có các tài liệu 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 giúp người dùng cuối của Rucio có được trải nghiệm liền mạch trong khi sử dụng khung này bằng cách cung cấp một chế độ xem tập trung để truy cập vào tất cả tài liệu có liên quan.

Trạng thái hiện tại: Cho đến ngày nay, tài liệu về người dùng được trải rộng ở nhiều nơi và ở nhiều định dạng, bao gồm các bài viết khoa học, readthedocs.io kèm nguồn trong mã, Google Drive, GitHub, DockerHub hoặc Wikis. Nhiều nguồn gây ra các vấn đề về việc theo dõi các 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 gây trở ngại đáng kể trong việc di chuyển và cung cấp 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 Wikis, thông tin được cung cấp cho một thử nghiệm cụ thể cũng có thể áp dụng rất tốt cho các trường hợp 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 phù hợp, thông tin này không hoạt động và có thể không được sử dụng đúng mức.

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

Việc sắp xếp lại cấu trúc tài liệu nhằm mục đích đơn giản hoá những công việc dành cho việc điều hướng cho người dùng cuối. Họ không cần phải đi tìm thông tin vì chúng 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 tự do phân loại dựa trên yêu cầu. Tập trung tất cả tài liệu có cấu trúc tập trung để đảm bảo rằng người dùng có thể nhìn thấy tất cả thông tin mà không cần phải tham khảo nhiều nguồn.

Phân tích: Sau khi đọc bản tóm tắt về các yêu cầu và trao đổi với nhóm cố vấn, tôi thấy các thông tin khấu trừ về tình trạng hiện tại của tài liệu Rucio như sau:

Có sáu 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 với nguồn trong mã Liên kết đến Mã: https://github.com/rucio/rucio Liên kết đến ReadtheDocs: https://rucio.readthedocs.io/en/latest/

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

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

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

  • 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 ở 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 bằng ngôn ngữ đánh dấu restructureText, v.v. Thiếu phiên bản và theo dõi dẫn đến thông tin thừa được xuất bản 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à chuyên môn trước đây khi tìm kiếm.

Với vô số định dạng và nguồn thông tin, chúng tôi hy vọng bạn sẽ cấu trúc lại thông tin 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à phân tán mà không có mối liên kết thích hợp. Hệ thống cũng thiếu tính tập trung và tính nhất quán trong định dạng. Điều này khiến người dùng phải tốn thêm nhiều nỗ lực cho việc tìm kiếm. Những lỗ hổng như vậy cũng tạo ra áp lực không cần thiết đối với các quản trị viên/người bảo trì/trưởng nhóm, do đó khó duy trì phương pháp tiếp cận theo hướng cộng đồng cho việc bảo trì và cập nhật tài liệu. Trải nghiệm của người dùng và người đóng góp đã bị suy giảm đáng kể và tình trạng này sẽ lặp lại

Cấu trúc của tài liệu được đề 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 sắp xếp lại.
Mô hình tái cấu trúc được minh hoạ trên bản minh hoạ đính kèm bên dưới và sẽ phân loại mọi tài liệu vào 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
  • Bí quyết nâng cao

Tất nhiên, sẽ có các điểm cải tiến, chẳng hạn như thêm đường liên kết mà tôi muốn thực hiện sau khi hoàn tất chương trình này. Với hơn 1000 người dùng đang hoạt động truy cập vào 500 petabyte dữ liệu trên Rucio, đề xuất tái cấu trúc tài liệu của công cụ này có thể giảm đáng kể nhu cầu người dùng sử dụng danh sách gửi thư hỗ trợ. Mục tiêu của chương trình 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 tính năng phân loại và gắn nhãn. Mọi thông tin cần biết từ góc độ người dùng/hoạt động/nhân viên quản trị sẽ được cung cấp trong vòng tối đa 3 lượt nhấp.

Đường liên kết mô phỏng: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

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

Cơ bản cho hệ thống này đã sẵn sàng. Tuy nhiê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 đưa ra các nguyên tắc phù hợp cho việc đóng góp và quản trị thông qua tài liệu phù hợp. Hơn nữa, tôi hình dung việc 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 hiện tại và Rucio --> 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 (từ 17/8 – 13/9) --> Thiết lập kênh liên lạc và thời gian để trao đổi về sự chênh lệch giữa các múi giờ (Pune trước 3 giờ 30 phút) --> Các vấn đề chính cần xác định để hoàn thiện mục tiêu --> Tìm hiểu thêm về cộng đồng, tổ chức và khung thời gian bằng cách tham gia trò chuyện. --> Đánh giá cấu trúc tài liệu đề xuất với người cố vấn và các thành viên chủ chốt khác trong tổ chức để xác định tính khả thi và tính khả thi của việc triển khai. --> Hoàn thiện các tính năng được đề xuất và mọi sửa đổi khác có thể cần thực hiện đối với tài liệu hiện có.

  • Giai đoạn lập tài liệu (14/9 – 30/11) Trên cơ sở định dạng đề xuất mà tôi đã tạo ở đây, tôi đã trình bày chi tiết các mốc quan trọng mà tôi dự định đạt được trong giai đoạn lập tài liệu.

--> Cột mốc số 1: Phân loại và gắn nhãn ETC: Ngày 28 tháng 9 năm 2020 Việc đồng bộ hoá tài liệu có sẵn 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.

--> Cột mốc số 2: Phân tích, cắt giảm 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 Cột mốc số 1 sẽ được phân tích để xem các nội dung trùng lặp + nguồn thông tin dư thừa. Như đã nêu trong thông tin dự án, chúng tôi hướng đến một nguồn đáng tin cậy cho tất cả thông tin có sẵn.

--> Cột mốc số 3: Tập trung và định dạng lại: ETC: Ngày 9 tháng 11 năm 2020 Sau khi bạn cắt bớt và sắp xếp lạ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ác nguồn khác nhau, các định dạng sẽ khác nhau và trước tiên cần được chuyển đổi thành một định dạng phù hợp. Sau khi hoàn thành việc này, quá trình tập trung sẽ trở nên dễ dàng hơn.

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

--> Đánh giá dự án (30/11 – 5/12) Gửi báo cáo dự án và đánh giá các người cố vấn của tôi Viết và gửi báo cáo trải nghiệm của tôi khi tham gia Phần Tài liệu.

Tại sao có dự án này? Tôi tin rằng việc bổ sung mã bằng tài liệu được viết và tạo phiên bản là cách duy nhất để có thể tiếp tục áp dụng và sử dụng tốt hơn. Cá nhân, tôi bị cuốn hút bởi cách CERN tiên phong trong việc đi tiên phong nghiên cứu trong các lĩnh vực Vật lý khác nhau. Với quy mô thông tin được xử lý, chuyển giao và tạo ra trong những thử nghiệm như vậy, tôi luôn băn khoăn về cách dữ liệu được quản lý để tham khảo và sử dụng trong tương lai trong tổ chức. Chúng tôi có vinh dự được đóng góp vào việc cải tiến tài liệu cho một bộ 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 rằng mình sẽ là người phù hợp cho dự án này vì:

Tôi đang bắt tay vào sửa đổi tài liệu hiện có cho Kubernetes. Nhờ những nội dung đóng góp này, tôi được ghi tên vào danh sách Bóng đổ của Tài liệu phát hành trong chu kỳ Bản 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 bổ sung trong các bản phát hành. Tôi tin rằng tài liệu chất lượng cao chính là nền tảng cho một sản phẩm/dịch vụ chất lượng cao. Thông tin được viết chỉn chu, súc tích và dễ tiếp cận sẽ là động lực thúc đẩy quá trình áp dụng và hỗ trợ việc sử dụng, cho dù đó là về mặt quy trình hay kỹ thuật. Sau khi làm việc với các hệ thống phân phối dựa trên dữ liệu trong suốt sự nghiệp của mình, tôi tin rằng mình 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 tài liệu về những hệ thống đó. Bản thân cũng là người dùng cuối nên tôi quen với những sai lầm của việc viết tài liệu trình bày sơ sài/không chính xác. Vì vậy, tôi sẽ cẩn thận cân nhắc những điều này trong quá trình tái cơ cấu.