Project CERN-HSF

Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season Dokumen.

Ringkasan proyek

Organisasi open source:
CERN-HSF
Penulis teknis:
Aria
Nama proyek:
Rucio – Memodernisasi (merestrukturisasi & menulis ulang) dokumentasi Rucio
Durasi proyek:
Durasi standar (3 bulan)

Project description

Abstrak: Framework Rucio dikembangkan dengan tujuan untuk mengelola dan mengatur data ilmiah yang didistribusikan secara geografis dalam jumlah besar di berbagai pusat data heterogen. Framework ini menawarkan kemampuan seperti pemulihan data terdistribusi dan replikasi adaptif, sehingga framework ini sangat skalabel, modular, dan dapat diperluas. Konsumen dokumentasi untuk layanan semacam itu akan berasal dari berbagai latar belakang dan memiliki persyaratan yang beragam saat mengaksesnya. Oleh karena itu, dokumentasi yang baik untuk layanan tersebut harus menyederhanakan adopsi dan pemanfaatannya untuk pengguna akhir sekaligus menjadi referensi untuk masalah umum & pemecahan masalah.

Dengan tidak adanya dokumentasi tersebut, akan ada rintangan yang signifikan dalam pemanfaatan yang efisien & efektif. Hal ini berpotensi meningkatkan biaya dukungan dan menimbulkan risiko reputasi pada identitas perusahaan produk tersebut. Bagaimanapun juga, dokumentasi adalah suatu mode komunikasi. Oleh karena itu, memastikan komunikasi dienkapsulasi dalam framework yang mudah dikelola & dapat diakses sambil tetap relevan dengan pembuatan versi yang tepat adalah dengan memastikan bahwa kami berkomunikasi untuk meraih kesuksesan.

Pada saat penulisan ini, framework Rucio telah digunakan untuk mendukung persyaratan energi tinggi dari eksperimen ATLAS dan CMS di LHC. Alat ini juga digunakan untuk mendukung kebutuhan komunitas ilmiah di luar LHC, seperti astrofisika; sehingga dokumentasi dibuat serelevan dan sebisa mungkin. Dengan bantuan project ini, CERN ingin pengguna akhir Rucio mendapatkan pengalaman yang lancar sambil memanfaatkan framework dengan menyediakan tampilan terpusat untuk mengakses semua dokumentasi yang relevan.

Status Saat Ini: Mulai hari ini, dokumentasi pengguna tersebar di berbagai tempat dan dalam berbagai format, termasuk artikel ilmiah, readthedocs.io dengan sumber dalam kodenya, Google Drive, GitHub, DockerHub, atau Wiki. Banyak sumber menimbulkan masalah terkait pelacakan versi dan ketepatan dokumentasi. Selain itu, model dokumentasi yang terdesentralisasi menimbulkan rintangan yang signifikan dalam navigasi dan memunculkan informasi yang relevan untuk kasus penggunaan tertentu. Terutama untuk Wiki, informasi yang diberikan untuk eksperimen tertentu juga dapat diterapkan pada instance lain yang ada di sumber yang sama/lain. Namun, karena kurangnya konsolidasi dan hubungan yang sesuai, informasi ini tidak aktif dan berpotensi kurang dimanfaatkan.

Mengapa dokumentasi pengguna yang Anda usulkan lebih baik dari yang saat ini? Dengan mempertimbangkan masalah multi-aspek, model yang diusulkan di bawah ini mengatasi masalah navigasi, pembuatan versi, pelacakan, dan kemunculan dokumentasi seperti yang dijelaskan di bawah ini:

Restrukturisasi dokumentasi bertujuan untuk menyederhanakan upaya yang dikeluarkan dalam menavigasi untuk pengguna akhir. Ia tidak perlu mencari-cari informasi karena informasi akan dikategorikan/diberi label untuk kemudahan. Dari perspektif administratif, pembuatan versi & pelacakan akan lebih mudah karena restrukturisasi akan menawarkan kebebasan untuk mengategorikan berdasarkan persyaratan. Memusatkan semua dokumentasi yang disusun ulang adalah untuk memastikan bahwa semua informasi terlihat oleh pengguna tanpa harus merujuk ke banyak sumber.

Analisis: Setelah membaca ringkasan persyaratan & berdiskusi dengan tim bimbingan, potongan saya atas status dokumentasi Rucio saat ini adalah sebagai berikut:

Ada enam sumber utama dokumentasi: - Link Google Drive : https://drive.google.com/drive/folders/1EEN8l1dFjDSgavPrAMMooDjEodHP7aU7

  • Baca dokumen yang didukung oleh Sphinx dengan sumber dalam kode Link ke Kode: https://github.com/rucio/rucio Link ke ReadtheDocs: https://rucio.readthedocs.io/en/latest/

  • DockerHub Link: https://hub.docker.com/u/rucio

  • Link GitHub: https://github.com/rucio/rucio

  • Tautan Wikis: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing

  • Artikel Ilmiah Link: https://arxiv.org/abs/1902.09857

Dokumentasi di sumber-sumber ini menggunakan format yang berbeda. Misalnya, Google Drive memiliki dokumentasi dalam bentuk Slide dan Dokumen, GitHub memiliki file yang sebagian besar menggunakan bahasa markup reStructuredText, dll. Kurangnya pembuatan versi dan pelacakan yang menyebabkan banyak informasi dipublikasikan di berbagai sumber. Tidak ada keseragaman dalam pelabelan/kategorisasi informasi. Oleh karena itu, diperlukan pengalaman dan keahlian sebelumnya saat melakukan penelusuran.

Mengingat format & sumbernya yang sangat banyak, kami berharap dapat merestrukturisasi informasi dan memusatkannya menggunakan mkdocs. Untuk meningkatkan pemahaman saya tentang alat-alat tersebut, saya telah meneliti dan memahami penggunaannya.

Putusan: Dokumentasi yang ada tidak terstruktur dan tersebar tanpa penautan yang sesuai. Juga tidak memiliki sentralisasi & keseragaman dalam format. Akibatnya, pengguna harus berusaha ekstra keras untuk melakukan penelusuran. Kesenjangan tersebut juga menimbulkan tekanan yang tidak perlu pada administrator/pemelihara/pimpinan karena sulit dalam mempertahankan pendekatan berbasis komunitas untuk pemeliharaan & pembaruan dokumentasi. Pengalaman pengguna & kontributor mengalami penurunan kualitas yang signifikan dan akan terjadi pengulangan

Struktur untuk dokumentasi yang diusulkan: Setelah analisis persyaratan secara menyeluruh, saya memutuskan untuk mengatasi poin masalah utama melalui model dokumentasi yang direstrukturisasi.
Model yang direstrukturisasi ditunjukkan melalui mock-up yang dilampirkan di bawah dan akan mengategorikan setiap dokumentasi ke dalam 7 kategori di bawah:

  • Tentang
  • Memulai
  • Konsep
  • Antarmuka Rucio
  • Tugas
  • Tutorial
  • Pengetahuan tingkat lanjut

Tentu saja, ada peningkatan seperti menambahkan link yang ingin saya kerjakan setelah menyelesaikan program ini. Dengan lebih dari 1.000 pengguna aktif yang mengakses 500 petabyte data di Rucio, restrukturisasi yang diusulkan pada dokumentasinya seharusnya dapat secara signifikan mengurangi kebutuhan pengguna untuk menggunakan milis dukungan. Targetnya adalah Pengalaman Pengguna yang lebih baik dengan menurunkan jumlah rasio klik & dengan mudah menampilkan dokumentasi melalui kategorisasi & pelabelan. Segala sesuatu yang ingin diketahui dari perspektif pengguna/operasi/petugas admin akan tersedia dalam 3 klik atau kurang.

Tautan maket: https://drive.google.com/file/d/1vSYgOkB9s9eEr2soNs7ujMLHzDlKn_hr/view?usp=sharing)

Tujuan Proyek: - Menganalisis dan memangkas informasi berlebihan yang tersedia dari berbagai sumber, yaitu setiap informasi harus memiliki satu sumber kebenaran. - Mengubah struktur dokumentasi yang ada dengan memberi label & mengelompokkan dokumentasi yang ada ke dalam berbagai bagian - Memigrasikan dokumentasi yang disusun ulang ke tampilan terpusat berdasarkan mkdocs - Memformat ulang/mengimpor dokumentasi yang tidak dapat dimigrasikan karena batasan format file - Menyiapkan modifikasi dokumentasi berbasis komunitas untuk memastikan semua kesenjangan yang hilang telah diisi - dalam hal penautan, pembaruan informasi, atau koreksi kesalahan.

Barebone untuk sistem ini sudah ada, tetapi model saya akan memperbaiki sistem yang sudah ada dengan memberikan panduan yang tepat untuk kontribusi & tata kelola dengan dokumentasi yang sesuai. Selain itu, saya membayangkan menggabungkan papan project GitHub untuk melacak masalah dan kesiapan proyek secara keseluruhan.

Linimasa: - Sebelum 16 Agustus --> Membiasakan diri dengan versi dokumentasi saat ini & Rucio --> Mempelajari teknik baru dan keterampilan menulis teknis yang akan berguna selama jangka waktu project --> Berkontribusi terhadap masalah dokumentasi, jika ada, yang dilaporkan di GitHub

  • Ikatan komunitas (17 Agustus - 13 September) --> Siapkan saluran dan waktu komunikasi untuk menjelaskan perbedaan zona waktu (Pune berjarak 3 jam 30 menit ke depan) --> Poin masalah utama yang harus diidentifikasi terhadap penyempurnaan tujuan --> Pelajari lebih lanjut komunitas, organisasi, dan kerangka kerja dengan terlibat dalam percakapan. --> Penilaian terhadap struktur dokumentasi yang diusulkan dengan mentor dan anggota utama organisasi lainnya terkait kelangsungan & kelayakan implementasi. --> Penyelesaian fitur yang diusulkan dan modifikasi lain yang mungkin perlu dilakukan pada dokumentasi yang ada.

  • Periode Dokumentasi (14 September - 30 November) Berdasarkan format yang diusulkan yang saya rumuskan di sini, saya memberikan perincian pencapaian utama yang ingin saya capai selama periode dokumentasi.

--> Pencapaian #1: Kategorisasi & Pelabelan ETC: 28 September 2020 Mengasimilasi dokumentasi yang tersedia dan melabelinya akan sangat menyederhanakan proses restrukturisasi & pemangkasan.

--> Pencapaian #2: Analisis, Pemangkasan & Restrukturisasi ETC: 19 Oktober 2020 Dokumentasi yang telah dikategorikan selama Pencapaian #1 akan dianalisis untuk memeriksa adanya duplikasi + sumber informasi yang berlebihan. Sebagaimana dinyatakan dalam informasi project, kami menargetkan satu sumber tepercaya untuk semua informasi yang tersedia.

--> Pencapaian #3: Pemusatan & Pemformatan Ulang: ETC: 9 November 2020 Setelah dokumentasi dipangkas & disusun ulang dengan benar, saya akan memformat ulang dokumen tersebut terlebih dahulu. Karena berbagai sumber, formatnya pun berbeda dan harus diubah terlebih dahulu ke dalam format yang sesuai. Setelah ini selesai, proses sentralisasi akan menjadi lebih mudah.

--> Pencapaian #4: Menyiapkan papan pelacakan + dokumentasi seputar tata kelola/kontribusi ETC: 23 November 2020 Fase ini adalah untuk memastikan bahwa setelah penyelesaian proyek, dokumentasi terus diperbarui. Meletakkan pedoman dan menyiapkan dewan proyek akan meringankan beban anggota administratif untuk meminta kontribusi komunitas dan melacaknya secara efektif.

--> Evaluasi Proyek (30 November - 5 Desember) Mengirimkan laporan proyek dan evaluasi mentor Menulis dan mengirim laporan pengalaman sebagai peserta dalam Musim Dokumen.

Mengapa proyek ini? Saya yakin bahwa kode tambahan dengan dokumentasi yang ditulis dan berversi adalah satu-satunya cara untuk memungkinkan adopsi lebih lanjut & penggunaan yang lebih baik. Secara pribadi, saya terpesona dengan cara CERN memelopori penelitian mutakhir di berbagai bidang Fisika. Mengingat skala informasi yang diproses, ditransfer, dan dihasilkan selama eksperimen tersebut, saya selalu tertarik dengan cara data dikelola untuk referensi & penggunaan di masa mendatang dalam organisasi. Suatu kehormatan dapat berkontribusi terhadap peningkatan dokumentasi untuk sebuah kerangka kerja yang telah mendukung beberapa penelitian dan penemuan ilmiah yang luar biasa.

Mengapa saya adalah orang yang tepat untuk proyek ini? Selain memenuhi prasyarat, saya yakin saya akan menjadi orang yang tepat untuk project ini karena:

Saya sudah berupaya memodifikasi dokumentasi yang ada untuk Kubernetes. Kontribusi ini membuat saya terdaftar sebagai Release Docs Shadow untuk siklus Rilis Kubernetes 1.19 di mana saya berkontribusi untuk memelihara dan mengupgrade dokumentasi secara efektif untuk fitur baru yang ditambahkan selama rilis. Saya percaya bahwa dokumentasi yang baik adalah fondasi utama untuk produk/layanan yang hebat. Baik itu prosedural atau teknis, informasi yang ditulis dengan baik, ringkas, dan mudah diakses akan menjadi dorongan dalam mendorong adopsi & membantu penggunaan yang lebih baik. Setelah bekerja dengan sistem terdistribusi berbasis data di sepanjang karier saya, saya yakin bahwa saya berada di posisi terbaik untuk memahami seluk-beluk persyaratan sehubungan dengan dokumentasi untuk sistem tersebut. Pernah menjadi pengguna akhir, saya memahami jebakan dokumentasi yang tidak ditulis dengan baik/salah dan akan berhati-hati untuk mengakomodasi hal-hal tersebut selama restrukturisasi.