Proyek Wikimedia Foundation

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

Ringkasan project

Organisasi open source:
Wikimedia Foundation
{i>Technical writer <i}(Penulis teknis):
Pavithra Eswaramoorthy
Nama project:
Meningkatkan kualitas dokumentasi untuk videografer dan pembuat dokumentasi teknis Wikimedia
Durasi project:
Durasi standar (3 bulan)

Project description

1. Tentang saya

Saya diperkenalkan dengan software open source beberapa bulan lalu dan hampir langsung merasa kewalahan dengan cakupannya yang tidak terbatas. Dalam upaya untuk menyelesaikan banyak project, saya mempelajari inisiatif open source seperti Google Summer of Code dan Outreachy. Google Season of Docs tampak menarik dan ide project dari Wikimedia Foundation membangkitkan rasa penasaran saya, jadi saya mulai mempelajarinya lebih lanjut.

Perjalanan saya sejauh ini menyenangkan sekaligus membingungkan, penuh dengan “Tunggu, apa?”, “Ahh, saya mengerti!”, dan “Haruskah saya mengomentari ini?”. Komunitas Wikimedia telah mendukung saya di setiap langkah. Dari mengedit halaman hingga membuat ekstensi, saya belajar hal baru setiap hari.

Seperti yang diharapkan, proses aplikasi berfungsi sebagai pintu masuk saya ke komunitas {i>open source<i}. Proposal ini terinspirasi dari pengalaman saya sendiri sebagai pemula.

2. Project

2.1. Garis batas

Project ini bertujuan untuk meningkatkan kualitas dokumentasi bagi penulis teknis dan calon videografer di seluruh Wikimedia. Kumpulan pedoman dokumentasi teknis yang matang akan membantu meningkatkan kualitas dokumentasi secara keseluruhan, dan referensi untuk membuat screencast akan memungkinkan demonstrasi fitur software secara efektif. Dokumentasi yang ada di area ini dapat diperluas untuk lebih mendukung pendatang baru dan kontributor berpengalaman. Pendekatan inkremental akan diterapkan untuk mengembangkan jaringan referensi praktis ini.

2.2. Hasil

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

    • Menambahkan tips dan contoh ke panduan Dokumentasi/Gaya. [https://www.mediawiki.org/wiki/Documentation/Style_guide]
    • Tambahkan informasi khusus MediaWiki ke genre tertentu dalam template dan saran Dokumentasi teknis: Panduan pengguna, petunjuk, panduan memulai cepat, catatan rilis, dan README. [https://www.mediawiki.org/wiki/Technical_documentation_templates_and_suggestions]
    • Menguji dan Meningkatkan panduan untuk Prioritas dokumentasi teknis. [https://www.mediawiki.org/wiki/Technical_documentation_prioritization]
    • Mendesain strategi pengumpulan konten untuk berbagai genre dokumentasi.
    • Buat desain strategi komunikasi dan kolaborasi untuk dokumentasi MediaWiki.
    • Buat checklist yang dapat digunakan penulis untuk meninjau dokumen mereka sebelum dipublikasikan.
    • Memperluas struktur dokumentasi untuk penulis teknis baru. [https://www.mediawiki.org/wiki/User:Pavithraes/Sandbox/New_Technical_Writers]
    • Buat daftar tugas dokumentasi teknis yang cocok untuk hackathon. [https://www.mediawiki.org/wiki/Technical_Documentation_Tasks_for_Hack-a-thons]
    • Buat hub penulis teknis yang mengarah ke referensi yang berguna.

  • Meningkatkan kualitas dokumentasi untuk videografer MediaWiki:

    • Buat panduan pengguna singkat untuk membuat screencast umum.
    • Buat desain template screencast khusus MediaWiki untuk panduan dan tutorial.

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

2.3. Sasaran Tambahan

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

3. Mentor

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

4. Diskusi

Proyek ini secara luas dibagi menjadi dua fase:

(i) Meningkatkan kualitas referensi yang ada untuk penulis teknis Wikimedia.

(ii) Membuat template yang berguna bagi calon videografer.

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

Sebelumnya, ada beberapa inisiatif untuk meningkatkan kualitas dokumentasi MediaWiki dengan tingkat keberhasilan yang bervariasi. 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 kumpulan referensi yang lebih baik untuk penulis teknis akan berdampak langsung pada dokumen yang dihasilkan oleh mereka.

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

“Panduan gaya MediaWiki jauh dari sempurna, terutama karena terlalu mengandalkan referensi eksternal tanpa menyoroti praktik mana yang dianggap terbaik. Sayangnya, masalah ini tidak hanya terbatas pada MediaWiki, karena muncul di dokumentasi lain seperti Praktik terbaik terjemahan. Penulis akhirnya tidak memiliki referensi yang baik dan andal untuk melakukan pekerjaan mereka, sehingga kesulitan dalam menetapkan target audiens dan gaya penulisan yang tepat. Dan pengguna, terutama pengguna baru, mungkin menghadapi masalah untuk memahami konsep dan proses baru.”

T197006 [https://phabricator.wikimedia.org/T197006] juga menjelaskan area tertentu dalam dokumentasi penulisan teknis yang perlu ditingkatkan. Jelas, Documentation/Style_guide adalah tempat untuk memulai.

Setelah kita memiliki panduan gaya yang lebih baik, seperangkat dokumen berikutnya direncanakan untuk memandu penulis teknis melalui berbagai tahap penulisan teknis. Dokumen harus mudah digunakan oleh pemula dan sekaligus memberikan semua informasi yang diperlukan untuk penulis agar dapat merujuk kembali.

Tahap persiapan mungkin adalah yang paling penting karena meletakkan dasar untuk pembuatan dokumen. Untuk mendukung penulis teknis selama tahap ini, dokumen referensi dikembangkan yang menjelaskan beberapa cara efektif untuk mengumpulkan informasi yang relevan dan tips tentang cara menyusun informasi ini menggunakan template.

Kemudian, tahap penulisan. Penulis diberi contoh karya yang baik untuk secara otomatis menetapkan standar yang tinggi. Selain itu, checklist dibuat dengan serangkaian kriteria dasar yang harus diikuti setiap dokumen. Hal ini akan membantu penulis meninjau dokumen mereka sebelum memublikasikannya.

Bahkan dengan dokumen-dokumen ini, penulis teknis baru akan membutuhkan bantuan tambahan, dan kita harus memberikannya kepada mereka. Panduan untuk penulis teknis baru telah ditingkatkan dan daftar tugas yang sesuai untuk hackathon diseleksi berdasarkan tingkat kesulitannya.

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

Di akhir fase ini, hub panduan, referensi, contoh, saran, dan template penulisan teknis akan dibuat untuk mendukung panduan gaya dokumentasi.

(ii) Membuat template yang berguna bagi calon videografer.

“Salah satu cara tersulit untuk mempelajari apa pun yang melibatkan grafik adalah dengan membaca teks biasa. Bayangkan juga apa yang terjadi jika manual Anda merujuk ke versi software yang salah - dengan manual khusus teks, sering kali kita tidak dapat membuat ulang serangkaian tindakan saat menu dan kata-kata dalam aplikasi berubah karena kita tidak memiliki semua petunjuk yang biasanya kita gunakan.

Mungkin cara terbaik untuk belajar adalah dengan didampingi pakar yang duduk tepat di samping Anda. Screencast berada di antara grafis statis dan memiliki pakar yang siap membantu. Kita mendapatkan demo visual yang bergerak dengan suara yang ramah, kita juga dapat memiliki anotasi teks di layar dan animasi. Keuntungan screencast dibandingkan dengan pakar adalah screencast 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 di atas dari ""The Screencasting Handbook"" [https://thescreencastinghandbook.com/wp-content/uploads/The_Screencasting_Handbook_rel10_20100502_v6.pdf], Ian Ozsvald menjelaskan signifikansi screencast. Hal ini sangat berguna untuk tutorial tentang cara menyiapkan lingkungan pengembangan MediaWiki, menulis ekstensi, menggunakan Gerrit, dan lainnya.

Serupa dengan template untuk dokumen, memiliki template standar untuk screencast akan mendorong keseragaman, sehingga meningkatkan pengalaman penonton. Video ini juga memberikan framework untuk memulai kepada calon videografer. Oleh karena itu, panduan pengguna cepat yang diikuti dengan template untuk membuat video pengantar dan tutorial dikembangkan. Dokumen ini menyertakan petunjuk tentang kedalaman konsep yang akan dibahas dan beberapa ide screencast untuk MediaWiki.

Cara terbaik untuk menguji template di atas dan mempersiapkan sasaran tambahan adalah dengan membuat screencast menggunakan alat dan template. Oleh karena itu, screencast “Pengantar Phabricator” yang membahas dasar-dasar penggunaan Phabricator dibuat. Proses ini juga akan menyoroti area-area yang perlu dibahas.

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

5. Linimasa sementara

Periode ikatan komunitas (1 Agustus - 1 September)

  • Menganalisis project secara mendetail dengan mentor saya.

  • Diskusikan tentang:

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

  • Membuat tugas dan subtugas yang diperlukan di Phabricator.

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

Minggu ke-1 (2 - 8 September)

  • Meningkatkan kualitas Dokumentasi/Panduan_gaya:

    • Mengalihkan fokus utama untuk mengilustrasikan praktik terbaik dan standar di MediaWiki.
    • Sertakan contoh hasil kerja yang baik dan tingkatkan visibilitas halaman terkait.

  • Meningkatkan panduan untuk Penulis teknis baru:

    • Luaskan struktur dokumentasi.

Minggu ke-2 (9 - 15 September)

  • Kerjakan Prioritas dokumentasi teknis:

    • Evaluasi papan kerja dokumentasi; temukan contoh deskripsi dan prioritas tugas yang baik.
    • Pelajari trennya dan catat kesulitan yang umum terjadi.
    • Gunakan informasi dan contoh untuk mendokumentasikan standar prioritas.

Minggu ke-3 (16 - 22 September)

  • Buat dokumentasi tambahan berikut untuk penulis teknis:

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

Minggu 4 (23 - 29 September)

  • Tambahkan informasi tentang penulisan dalam genre MediaWiki yang paling umum ke template dan saran Dokumentasi teknis:

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

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

Minggu 5 (30 September - 6 Oktober)

  • Meningkatkan dokumentasi untuk orientasi kolaborator baru:

    • Memperbarui halaman: Tugas dokumentasi teknis untuk hackathon. (Tugas: Tambahkan tugas yang sesuai ke halaman ini selama periode project)

  • 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 di antara keduanya.

Minggu ke-6 (7 - 13 Oktober)

  • Buat dokumen berikut tentang cara membuat video untuk MediaWiki:

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

  • Buat daftar ide screencast untuk MediaWiki.

Minggu ke-7 (14-20 Oktober)

  • Tonton video ""Pengantar Phabricator"":

    • Gunakan template (yang dibuat minggu sebelumnya) untuk membuat draf skrip.
    • Estimasikan efisiensi template dan tingkatkan jika perlu.
    • Dapatkan masukan dan selesaikan draf.

Minggu ke-8 (21 - 27 Oktober)

  • Publikasikan video “Introduction to 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 dokumentasi project Screencast:

    • Periksa strukturnya dan diskusikan apakah perlu perubahan.
    • Tinjau software yang disebutkan.
    • Meneliti dan memperbarui daftar software.

Minggu ke-10 (4 - 10 November)

  • Terus tingkatkan kualitas dokumentasi project Screencast:

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

Minggu ke-11 (11 - 17 November)

  • Selesaikan tugas pada dokumentasi project Screencast:

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

Minggu ke-12 (18 - 24 November)

  • Selesaikan tugas yang tertunda.

  • Tulis laporan akhir:

    • Lihat laporan dua mingguan/harian dan kumpulkan informasi yang diperlukan.
    • Rencanakan struktur laporan dan tulis draf.
    • Tingkatkan kualitas dan selesaikan draf berdasarkan masukan mentor.

Minggu ke-13 (25 - 29 November)

  • Kirimkan laporan akhir dan evaluasi mentor.

6. Pelacakan Progres

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

7. Komitmen Lainnya

Saya adalah mahasiswa purnawaktu dan semester musim gugur akademik saya tumpang-tindih dengan linimasa Musim Dokumen. Oleh karena itu, komitmen saya mencakup 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 untuk menghadiri konferensi publik pertama saya, PyCon India dari 12 hingga 15 Oktober, berkat lokasi yang bagus tahun ini. Saya yakin ini akan menjadi peluang besar untuk bertemu orang baru dan melakukan percakapan yang bermanfaat.

Untuk mengelola komitmen ini, linimasa sementara berisi tugas yang tidak terlalu penting dalam minggu yang sesuai. Saya ingin menyelesaikan tidak lebih dari 20 kredit inti pada semester musim gugur agar memiliki waktu yang cukup untuk pengembangan dokumen. (Siswa reguler menyelesaikan rata-rata 25 kredit per semester)