Halaman ini diterjemahkan oleh Cloud Translation API.

Project CERN-HSF

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

Ringkasan project

Organisasi open source:: CERN-HSF
{i>Technical writer <i}(Penulis teknis):: Ariadne
Nama proyek:: Rucio – Memodernisasi (mengubah struktur &menulis ulang) dokumentasi Rucio
Durasi project:: Durasi standar (3 bulan)

Project description

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

Dengan tidak adanya dokumentasi tersebut, akan ada rintangan signifikan dalam pemanfaatan yang efisien dan efektif. Hal ini berpotensi menyebabkan peningkatan biaya dukungan dan menimbulkan risiko reputasi terhadap identitas perusahaan produk. Bagaimanapun, dokumentasi adalah mode komunikasi. Oleh karena itu, memastikan bahwa komunikasi dienkapsulasi dalam framework yang dapat dikelola & diakses sekaligus tetap relevan dengan pembuatan versi yang sesuai akan memastikan bahwa kita berkomunikasi untuk meraih kesuksesan.

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

Status Saat Ini: Saat ini dokumentasi pengguna tersebar di berbagai tempat dan dalam berbagai format termasuk artikel ilmiah, readthedocs.io dengan kode sumber, Google Drive, GitHub, DockerHub, atau Wiki. Beberapa sumber menimbulkan masalah terkait pelacakan versi dan keakuratan dokumentasi. Selain itu, model dokumentasi yang terdesentralisasi menimbulkan hambatan yang signifikan dalam navigasi & menampilkan informasi yang relevan untuk kasus penggunaan tertentu. Khusus untuk Wiki, informasi yang diberikan untuk eksperimen tertentu juga dapat berlaku untuk instance lain yang berada di sumber yang sama/lain. Namun karena kurangnya konsolidasi dan hubungan yang tepat, informasi ini menjadi tidak aktif dan berpotensi kurang dimanfaatkan.

Mengapa dokumentasi pengguna yang Anda usulkan merupakan peningkatan dari dokumentasi saat ini? Mengingat masalah multifaset, model yang diusulkan di bawah ini menghilangkan rintangan dalam navigasi, pembuatan versi, pelacakan, dan kemunculan dokumentasi seperti yang dijelaskan di bawah ini:

Restrukturisasi dokumentasi bertujuan menyederhanakan upaya yang telah dilakukan dalam menavigasi pengguna akhir. Ia tidak perlu mencari-cari informasi saat mencari informasi karena informasi tersebut akan dikategorikan/diberi label karena kemudahan. Dari perspektif administratif, pembuatan versi &pelacakan akan menjadi mudah karena restrukturisasi akan menawarkan kebebasan untuk membuat kategori berdasarkan kebutuhan. Memusatkan semua dokumentasi yang disusun ulang akan memastikan bahwa semua informasi dapat dilihat oleh pengguna tanpa harus merujuk ke beberapa sumber.

Analisis: Setelah membaca ringkasan persyaratan & melakukan percakapan dengan tim pembimbing, deduksi saya tentang status dokumentasi Rucio saat ini adalah sebagai berikut:

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

Readthedocs 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/
Link DockerHub: https://hub.docker.com/u/rucio
Link GitHub: https://github.com/rucio/rucio
Wikis Tautan: https://twiki.cern.ch/twiki/bin/view/AtlasComputing/AtlasDistributedComputing
Artikel Ilmiah Link: https://arxiv.org/abs/1902.09857

Dokumentasi di seluruh sumber ini menggunakan format yang berbeda. Misalnya, Google Drive memiliki dokumentasi dalam bentuk Slide dan Dokumen, GitHub memiliki file terutama dalam bahasa markup reStructuredText, dll. Tidak ada pembuatan versi dan pelacakan yang menyebabkan informasi yang berlebihan dipublikasikan di beberapa sumber. Tidak ada keseragaman dalam pemberian label/pengkategorian informasi. Oleh karena itu, pengalaman dan keahlian sebelumnya diperlukan saat melakukan penelusuran.

Mengingat banyaknya format & sumber, harapannya adalah menyusun ulang informasi dan memusatkan informasi tersebut menggunakan mkdocs. Untuk meningkatkan pemahaman saya tentang alat tersebut, saya telah meneliti dan memahami penggunaannya.

Verdict: Dokumentasi yang ada tidak terstruktur dan tersebar tanpa penautan yang sesuai. Format ini juga tidak memiliki sentralisasi &keseragaman dalam format. Hal ini menyebabkan pengguna harus mengeluarkan upaya ekstra untuk melakukan penelusuran. Kesenjangan tersebut juga menimbulkan tekanan yang tidak perlu pada administrator/pemelihara/pemimpin sehingga sulit untuk mempertahankan pendekatan berbasis komunitas untuk pemeliharaan & memperbarui dokumentasi. Pengalaman pengguna &kontributor sangat menurun dan akan terjadi pengulangan

Struktur untuk dokumentasi yang diusulkan: Setelah analisis persyaratan yang menyeluruh, saya telah memutuskan untuk mengatasi poin masalah utama melalui model dokumentasi yang disusun ulang.
Model yang disusun ulang ditunjukkan pada mockup yang dilampirkan di bawah dan akan mengategorikan setiap bagian dokumentasi ke dalam 7 kategori di bawah:

Tentang
Memulai
Konsep
Antarmuka Rucio
Tugas
Tutorial
Pengetahuan lanjutan

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 dokumentasi yang diusulkan akan dapat secara signifikan mengurangi kebutuhan pengguna untuk menggunakan milis dukungan. Targetnya adalah meningkatkan Pengalaman Pengguna dengan menurunkan jumlah rasio klik & dengan menampilkan dokumentasi dengan mudah melalui kategorisasi & pemberian label. Semua yang perlu diketahui dari perspektif personel pengguna/operasi/admin akan tersedia dalam 3 klik atau kurang.

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

Sasaran Project: - Menganalisis dan memangkas informasi yang berlebihan yang tersedia dari berbagai sumber. Artinya, setiap informasi harus memiliki satu sumber tepercaya. - Menyusun ulang dengan memberi label & mengategorikan 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 yang didorong oleh komunitas untuk memastikan kesenjangan yang ada terisi - dalam hal penautan, pembaruan informasi, atau koreksi error.

Dasar-dasar sistem ini sudah ada, tetapi model saya akan meningkatkan sistem yang ada dengan menetapkan pedoman yang tepat untuk kontribusi & tata kelola dengan dokumentasi yang sesuai. Selain itu, saya membayangkan untuk menggabungkan papan project GitHub untuk melacak masalah dan kesehatan project secara keseluruhan.

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

Pengikatan komunitas (17 Agustus - 13 September) --> Menyiapkan saluran komunikasi dan waktu untuk memperhitungkan perbedaan zona waktu (Pune lebih cepat 3 jam 30 menit) --> Identifikasi poin masalah utama untuk meningkatkan kualitas sasaran --> Pelajari lebih lanjut komunitas, organisasi, dan framework dengan terlibat dalam percakapan. --> Penilaian struktur dokumentasi yang diusulkan bersama mentor dan anggota penting lainnya dari organisasi untuk 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 telah memberikan perincian pencapaian utama yang saya rencanakan untuk dicapai selama periode dokumentasi.

--> Pencapaian #1: Mengkategorikan & Memberi Label ETC: 28 September 2020 Menyerap dokumentasi yang tersedia dan memberi label pada dokumentasi tersebut akan sangat menyederhanakan proses restrukturisasi & pemangkasan.

--> Pencapaian #2: Analisis, Pemangkasan & Penyusunan Ulang ETC: 19 Oktober 2020 Dokumentasi yang telah dikategorikan selama Pencapaian #1 akan dianalisis untuk menemukan duplikat + sumber informasi yang redundan. Seperti yang dinyatakan dalam informasi project, kami menargetkan satu sumber tepercaya untuk semua informasi yang tersedia.

--> Pencapaian #3: Memusatkan & Memformat Ulang: ETC: 9 November 2020 Setelah dokumentasi dipangkas & disusun ulang dengan benar, saya akan mencoba memformat ulang terlebih dahulu. Karena berbagai sumber, formatnya berbeda dan harus diubah terlebih dahulu menjadi format yang sesuai. Setelah ini dilakukan, proses pemusatan 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 project selesai, dokumentasinya terus diperbarui. Menetapkan panduan dan menyiapkan papan project akan meringankan beban anggota administratif untuk meminta kontribusi komunitas dan melacaknya secara efektif.

--> Evaluasi Proyek (30 November - 5 Desember) Mengirim laporan proyek dan evaluasi mentor saya Menulis dan mengirim laporan tentang pengalaman saya sebagai peserta dalam Season Dokumen.

Mengapa project ini? Saya percaya bahwa melengkapi kode dengan dokumentasi yang ditulis dengan baik dan memiliki versi adalah satu-satunya cara untuk memungkinkan adopsi lebih lanjut & penggunaan yang lebih baik. Secara pribadi, saya sangat tertarik dengan cara CERN merintis riset 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. Saya merasa terhormat dapat berkontribusi dalam peningkatan dokumentasi untuk framework yang telah mendukung beberapa riset dan penemuan ilmiah yang luar biasa.

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

Saya sedang berupaya mengubah dokumentasi yang ada untuk Kubernetes. Berkat kontribusi ini, saya terdaftar sebagai Release Docs Shadow untuk siklus Rilis Kubernetes 1.19. Di sini, saya berkontribusi untuk mengelola dan mengupgrade dokumentasi secara efektif untuk fitur-fitur baru yang ditambahkan selama rilis. Saya percaya bahwa dokumentasi yang baik adalah tulang punggung untuk produk/layanan yang hebat. Baik prosedural maupun teknis, informasi yang ditulis dengan baik, ringkas, dan mudah diakses akan menjadi pendorong dalam mendorong adopsi & membantu penggunaan yang lebih baik. Setelah bekerja dengan sistem terdistribusi berbasis data sepanjang karier saya, saya yakin bahwa saya berada di posisi terbaik untuk memahami seluk-beluk persyaratan sehubungan dengan dokumentasi untuk sistem semacam itu. Sebagai pengguna akhir, saya terbiasa dengan jebakan dokumentasi yang tidak ditulis dengan baik/salah dan akan berhati-hati untuk mengakomodasi hal tersebut menjadi pertimbangan selama proses restrukturisasi.