Proyek Wikimedia Foundation

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

Ringkasan proyek

Organisasi open source:
Wikimedia Foundation
Penulis teknis:
Pavithra Eswaramoorthy
Nama proyek:
Meningkatkan kualitas dokumentasi untuk dokumenter dan videografer teknis Wikimedia
Durasi proyek:
Durasi standar (3 bulan)

Project description

1. Tentang saya

Saya diperkenalkan dengan perangkat lunak {i>open source<i} beberapa bulan lalu dan hampir langsung merasa kewalahan dengan ruang lingkupnya yang tak terbatas. Karena kesulitan untuk mengelola proyek bazillion tersebut, saya mempelajari tentang inisiatif open source seperti Google Summer of Code dan Mediationy. Google Season of Docs tampak menarik dan gagasan proyek oleh Wikimedia Foundation menggugah rasa ingin tahu saya, jadi saya mulai mengeksplorasi lebih jauh.

Perjalanan saya sejauh ini sama menyenangkannya dan membingungkan, dipenuhi dengan pertanyaan “Tunggu, apa?”, “Ahh, aku mengerti!” dan “Haruskah saya mengomentari ini?”. Komunitas Wikimedia sangat mendukung di setiap langkah. Dari mengedit halaman hingga membuat ekstensi, saya belajar hal baru setiap hari.

Seperti yang diharapkan, proses pendaftaran berfungsi sebagai gerbang saya ke komunitas {i>open source<i}. Proposal ini terinspirasi oleh pengalaman saya sendiri sebagai pemula.

2. Project

2.1. Garis keliling

Proyek ini bertujuan untuk meningkatkan dokumentasi bagi penulis teknis dan videografer potensial di seluruh Wikimedia. Serangkaian panduan dokumentasi teknis yang matang akan membantu menumbuhkan dokumentasi secara keseluruhan, dan referensi untuk membuat screencast akan memungkinkan demonstrasi fitur software secara efektif. Dokumentasi yang ada dalam area ini dapat diperluas untuk mendukung pendatang baru dan kontributor berpengalaman dengan lebih baik. Pendekatan inkremental akan diadopsi untuk mengembangkan jaringan sumber daya praktis ini.

2.2. Hasil

  • T197006 [https://phabricator.wikimedia.org/T197006] - Meningkatkan dokumentasi untuk para dokumenter Wikimedia:

    • Tambahkan tips dan contoh ke panduan Dokumentasi/Gaya. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Tambahkan informasi khusus MediaWiki ke genre tertentu dalam saran dan template dokumentasi Teknis: Panduan pengguna, petunjuk, panduan memulai cepat, catatan rilis, dan README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Uji dan Tingkatkan panduan untuk penentuan prioritas dokumentasi Teknis. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Desain strategi pengumpulan konten untuk berbagai genre dokumentasi.
    • Rancang strategi komunikasi dan kolaborasi untuk dokumentasi MediaWiki.
    • Membuat checklist siapa yang dapat meninjau dokumen mereka sebelum memublikasikannya.
    • Memperluas struktur dokumentasi untuk penulis teknis baru. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Buat daftar tugas dokumentasi teknis yang sesuai untuk hackathon. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Membuat pusat penulis teknis yang menunjuk ke sumber daya yang berguna.

  • Menyempurnakan dokumentasi untuk videografer MediaWiki:

    • Buat panduan pengguna cepat untuk membuat screencast umum.
    • Desain template screencast khusus MediaWiki untuk panduan dan tutorial.

  • T214522 [https://phabricator.wikimedia.org/T214522]- Buat screencast “Pengantar Phabricator”.

2.3. Sasaran Regang

  • Periksa kembali konten dan perbarui dokumentasi WikiProject Screencast. (https://en.wikipedia.org/wiki/Wikipedia:WikiProject_Screencast)

3. Mentor

Zulip akan menjadi mode komunikasi utama dengan mentor saya. Email dan channel IRC Wikimedia akan digunakan untuk diskusi dengan komunitas. Diskusi tentang tugas tertentu akan dilakukan di bagian komentar tugas Phabricator.

4. Diskusi

Proyek ini dibagi secara luas menjadi dua fase:

(i) Meningkatkan sumber daya yang ada untuk para penulis teknis Wikimedia.

(ii) Membuat template yang berguna untuk calon videografer.

(i) Meningkatkan sumber daya yang ada untuk para penulis teknis Wikimedia.

Sebelumnya, ada beberapa inisiatif untuk menyempurnakan dokumentasi MediaWiki dengan berbagai tingkat keberhasilan. Di antaranya:

  • https://www.mediawiki.org/wiki/User:Zakgreant/Tech_DocsPlan(2011--01/P6M)
  • https://www.mediawiki.org/wiki/User:Zakgreant/MediaWiki_Technical_Documentation_Plan
  • https://www.mediawiki.org/wiki/Thread:Project:Current_issues/RestructureMediaWiki.org(or:_Document_how_it_was_and_execute_it)
  • https://www.mediawiki.org/wiki/User:Waldir/Docs

Dari upaya ini, kita dapat memahami bahwa serangkaian sumber daya yang lebih baik bagi penulis teknis akan berdampak langsung pada dokumen yang dihasilkan oleh penulis tersebut.

Berikut ini adalah cuplikan dari laporan dua mingguan pekerja magang Pendampingan pada tahun 2018, Anna e só https://anna.flourishing.stream/2018/01/18/bringing-documentation-to-light/:

“Panduan gaya MediaWiki masih jauh dari sempurna, terutama karena terlalu mengandalkan referensi eksternal tanpa menyoroti praktik mana yang dianggap paling baik. Sayangnya, masalah ini tidak terbatas pada MediaWiki saja, karena juga muncul di dokumentasi lain seperti praktik terbaik Translation. Penulis tidak memiliki sumber daya yang baik dan dapat diandalkan untuk melakukan pekerjaan mereka, sehingga menyebabkan kesulitan dalam menetapkan target audiens dan gaya penulisan yang tepat. Dan pengguna, khususnya pengguna baru, mungkin menghadapi masalah untuk memahami konsep dan proses baru.”

T197006 [https://phabricator.wikimedia.org/T197006] juga menyoroti area tertentu dari dokumentasi penulisan teknis yang perlu perbaikan. Jelas, Dokumentasi/Style_guide adalah tempat untuk memulai.

Setelah kami memiliki panduan gaya yang lebih baik, rangkaian dokumen berikutnya direncanakan untuk memandu penulis teknis melewati berbagai tahap penulisan teknis. Dokumen harus mudah dibaca bagi pemula dan pada saat yang sama memberikan semua informasi yang diperlukan untuk dirujuk oleh penulis.

Tahap persiapan mungkin adalah yang paling penting karena meletakkan fondasi di mana dokumen dibangun. Untuk mendukung penulis teknis melewati tahap ini, dokumen referensi dikembangkan yang menjelaskan beberapa cara efektif untuk mengumpulkan informasi yang relevan dan tips dalam menyusun informasi ini menggunakan template.

Lalu tibalah tahap menulis. Penulis diberi contoh pekerjaan yang baik untuk menetapkan standar yang tinggi secara otomatis. Selain itu, {i>checklist<i} dibuat dengan serangkaian kriteria dasar yang harus diikuti setiap dokumen, ini akan membantu penulis meninjau dokumen mereka sebelum menerbitkan.

Bahkan dengan dokumen ini, penulis teknis baru masih memerlukan bantuan tambahan, dan kami harus memberikannya. Panduan untuk penulis teknis baru disempurnakan dan daftar tugas yang sesuai untuk hackathon diseleksi berdasarkan tingkat kesulitan.

Terakhir, dokumen untuk memahami proses pengelolaan dan pemeliharaan dokumentasi - 'Prioritas dokumentasi teknis' diuji dan ditingkatkan.

Pada akhir fase ini, pusat panduan penulisan teknis, referensi, contoh, saran, dan {i>template<i} akan ditetapkan untuk mendukung panduan gaya dokumentasi.

(ii) Membuat template yang berguna untuk calon videografer.

“Salah satu cara tersulit untuk mempelajari apa pun yang melibatkan grafik adalah dengan membaca teks biasa. Bayangkan juga apa yang terjadi jika panduan Anda merujuk ke versi software yang salah - dengan panduan teks saja, sering kali mustahil untuk menciptakan kembali serangkaian tindakan saat menu dan kata-kata dalam aplikasi berubah karena kami tidak memiliki semua isyarat yang biasanya kami gunakan.

Mungkin cara terbaik untuk belajar adalah ketika Anda memiliki seorang ahli yang duduk tepat di samping Anda. {i>Screencast<i} berada di antara grafik statis dan memiliki pakar yang dekat. Kita mendapatkan demo visual yang bergerak dengan suara yang ramah. Kita juga dapat memiliki anotasi teks di layar dan animasi. Keuntungan screencast dibandingkan milik pakar adalah bahwa mereka dapat diputar ulang kapan saja setiap jam setiap hari.

Kami juga dapat menambahkan subtitel terjemahan ke screencast sehingga dapat ditonton oleh pengguna yang tidak mengerti bahasa Anda atau mengganti trek audio dengan bahasa lain.“

Dalam cuplikan dari ""The Screencasting Handbook" di atas, Ian Ozsvald menjelaskan pentingnya screencast. Alat ini sangat berguna untuk tutorial penyiapan lingkungan pengembangan MediaWiki, menulis ekstensi, menggunakan Gerrit, dan banyak lagi.

Mirip dengan template untuk dokumen, memiliki template standar untuk screencast meningkatkan keseragaman, sehingga meningkatkan pengalaman pengguna. Program ini juga memberikan kerangka kerja kepada calon videografer untuk memulai. Oleh karena itu, kami mengembangkan panduan pengguna cepat yang diikuti dengan {i>template<i} untuk membuat video pengantar dan tutorial. Dokumen ini mencakup petunjuk tentang kedalaman konsep yang akan dibahas dan beberapa ide screencast untuk MediaWiki.

Cara terbaik untuk menguji {i>template<i} di atas dan mempersiapkan tujuan peregangan adalah dengan membuat screencast menggunakan alat dan {i>template<i}. Oleh karena itu, screencast “Pengantar Phabricator” yang mencakup dasar-dasar penggunaan Phabricator dibuat. Proses ini juga akan menyoroti area yang perlu dibahas.

Terakhir, sumber utama referensi bagi videografer Wikimedia - WikiProject Screencast ditinjau dan diperbarui.

5. Linimasa tentatif

Periode ikatan komunitas (1 Agustus - 1 September)

  • Melakukan analisis proyek secara rinci dengan mentor saya.

  • Diskusikan tentang:

    • Seberapa sering tugas harus ditinjau.
    • Bagikan jadwal dan tentukan alur kerja mingguan/harian.
    • Alat dan resource yang dapat digunakan.
    • Laporan proyek dua mingguan dan harian.

  • Buat tugas dan subtugas yang diperlukan di Phabricator.

  • Buat draf untuk mengimbangi komitmen pribadi selama fase pengembangan dokumen.

Minggu ke-1 (2 - 8 September)

  • Memperbaiki Dokumentasi/Style_guide:

    • Geser fokus utama untuk menggambarkan praktik dan standar terbaik pada MediaWiki.
    • Sertakan contoh kinerja yang baik dan tingkatkan visibilitas halaman terkait.

  • Meningkatkan kualitas panduan untuk Penulis teknis baru:

    • Perluas struktur dokumentasi.

Minggu ke-2 (9 - 15 September)

  • Mengerjakan prioritas dokumentasi Teknis:

    • Menilai {i>workboard<i} dokumentasi; temukan contoh deskripsi dan prioritas tugas yang baik.
    • Pelajari tren dan catat kesulitan yang umum terjadi.
    • Gunakan informasi dan contoh untuk mendokumentasikan standar penentuan prioritas.

Minggu ke-3 (16 - 22 September)

  • Buat dokumentasi tambahan berikut untuk penulis teknis:

    • Checklist untuk membantu meninjau dokumentasi teknis sebelum memublikasikan.
    • Cara mengumpulkan konten secara efektif untuk berbagai genre dokumentasi.

Minggu ke-4 (23 - 29 September)

  • Tambahkan informasi tentang penulisan dalam genre MediaWiki yang paling umum ke {i>template<i} dan saran dokumentasi Teknis:

    • Dokumentasikan praktik terbaik di MediaWiki untuk menulis panduan pengguna, panduan memulai cepat, README, catatan rilis, dan petunjuk.

  • Tambahkan arah untuk meningkatkan kematangan komunikasi teknis. [https://www.mediawiki.org/wiki/User:SRodlund_(WMF)/Maturity_model_for_MediaWiki_technical_documentation#Increasingmaturity--_strategic_directions]

Minggu ke-5 (30 September - 6 Oktober)

  • Meningkatkan dokumentasi untuk memandu kolaborator baru:

    • Perbarui halaman: Tugas dokumentasi teknis untuk hackathon. (Daftar tugas: Tambahkan tugas yang sesuai ke halaman ini selama periode proyek)

  • Membangun hub penulis teknis

    • Buat halaman landing dengan link ke halaman dan referensi yang berguna.
    • Tambahkan link yang diperlukan ke halaman baru dan yang sudah ada untuk memudahkan navigasi antarhalaman.

Minggu ke-6 (7 - 13 Oktober)

  • Buat dokumen berikut tentang pembuatan video untuk MediaWiki:

    • Panduan pengguna cepat tentang 'membuat screencast umum' yang mengarah ke Screencast Project.
    • Template untuk: Panduan cara menggunakan software/alat; Tutorial tentang cara mengembangkan alat baru.

  • Buat daftar ide screencast untuk MediaWiki.

Minggu ke-7 (14-20 Oktober)

  • Buat video ""Introduction to Phabricator"":

    • Gunakan template (dibuat minggu sebelumnya) untuk membuat draf skrip.
    • Perkirakan efisiensi {i>template<i} dan perbaiki jika perlu.
    • Dapatkan masukan dan selesaikan draf.

Minggu ke-8 (21 - 27 Oktober)

  • Publikasikan video “Pengantar Phabricator”:

    • Pilih dan instal software.
    • Siapkan lingkungan dan buat screencast.
    • Catat masalah yang dihadapi dan solusinya.

Minggu ke-9 (28 Oktober - 3 November)

  • Berupaya meningkatkan kualitas dokumentasi project Screencast:

    • Periksa strukturnya dan diskusikan setiap kebutuhan akan perubahan.
    • Tinjau software yang disebutkan.
    • Cari informasi dan perbarui daftar software.

Minggu ke-10 (4 - 10 November)

  • Lanjutkan untuk meningkatkan kualitas dokumentasi project Screencast:

    • Mengevaluasi dan meningkatkan tutorial serta skrip.
    • Tinjau galeri screencast.

Minggu ke-11 (11 - 17 November)

  • Selesaikan pekerjaan di dokumentasi project Screencast:

    • Cari dan tambahkan video baru ke galeri.
    • Buat perubahan struktural yang diperlukan.

Minggu ke-12 (18 - 24 November)

  • Selesaikan semua tugas yang tertunda.

  • Tulis laporan akhir:

    • Lihat laporan dua mingguan/harian dan kumpulkan informasi yang diperlukan.
    • Rencanakan struktur laporan dan tulis drafnya.
    • Memperbaiki dan menyelesaikan draf berdasarkan umpan balik mentor.

Minggu ke-13 (25 - 29 November)

  • Kirimkan laporan akhir dan evaluasi mentor.

6. Pelacakan Kemajuan

Info terbaru tentang progres harian akan dikomunikasikan kepada mentor saya melalui Zulip. Komunitas Wikimedia dapat melacak kemajuan saya melalui Phabricator atau laporan proyek dua mingguan.

7. Komitmen Lainnya

Saya seorang mahasiswa purnawaktu dan semester musim gugur akademik saya tumpang-tindih dengan rentang waktu Musim Dokumen. Karenanya, komitmen saya termasuk ujian perguruan tinggi.

Ujian internal pertama: 18 hingga 24 Agustus

Ujian internal kedua: 29 September hingga 6 Oktober

Ujian akhir semester: 11 hingga 30 November

Saya juga berencana menghadiri konferensi publik pertama saya, PyCon India dari tanggal 12 sampai 15 Oktober, berkat lokasi yang bagus tahun ini. Saya percaya ini akan menjadi kesempatan bagus untuk bertemu orang baru dan melakukan percakapan yang bermanfaat.

Untuk mengelola komitmen ini, {i>timeline<i} tentatif berisi tugas-tugas yang tidak terlalu berat pada minggu-minggu yang sesuai. Saya bermaksud menyelesaikan tidak lebih dari 20 kredit inti pada semester musim gugur agar memiliki waktu yang cukup untuk pengembangan dokumen. (Seorang mahasiswa reguler rata-rata menyelesaikan 25 kredit per semester)