Fase saat ini:
Program Dokumen Musim 2019 selesai pada 6 Maret 2020. Lihat
linimasa.
Halaman ini berisi panduan bagi penulis teknis tentang cara membuat laporan project setelah Anda menyelesaikan tugas untuk Musim Dokumen tahun ini.
Mengirimkan laporan proyek
Saat fase finalisasi project terbuka, Anda dapat mengirimkan laporan project dengan melengkapi formulir yang tersedia di bagian finalisasi project di panduan penulis teknis.
Informasi yang harus disertakan dalam laporan proyek
Bagian ini menjelaskan jenis informasi yang dapat Anda berikan dalam laporan project. Formulir laporan proyek akan menyertakan bidang teks bebas serta pertanyaan pilihan ganda.
Link ke tugas Anda
Berikan tautan yang mengarah ke deskripsi pekerjaan yang telah Anda lakukan.
Link tersebut harus mengarah ke dokumen yang berisi deskripsi singkat tentang pekerjaan yang telah selesai, dokumentasi yang digabungkan oleh project open source ke dalam repositorinya, ringkasan status project saat ini, serta daftar tantangan dan pembelajaran.
Link tersebut akan muncul di hasil Season Dokumen yang dipublikasikan di situs. Hasil yang dipublikasikan menunjukkan pekerjaan yang telah Anda selesaikan selama program ini. Hasil yang dipublikasikan juga merupakan cara yang bagus untuk merujuk kembali ke pekerjaan Anda sebagai bagian dari resume.
Anda harus membagikan tautan Anda dengan mentor Anda dan meminta tinjauan sebelum mengirimkan laporan proyek Anda.
Persyaratan untuk laporan proyek
Perhatikan persyaratan berikut:
- Konten yang ditautkan harus memudahkan mengidentifikasi pekerjaan yang telah Anda selesaikan selama Season Dokumen, yaitu perubahan yang Anda buat atau dokumentasi baru yang Anda tulis.
- Pekerjaan harus berada di lokasi yang stabil. Anda tidak dapat mengubah URL setelah pengiriman.
Orang lain harus dapat menggunakan konten di (atau mereferensikan dari) target link untuk digunakan berdasarkan pekerjaan Anda.
- Jika pekerjaan Anda 100% selesai, orang lain harus dapat menggunakannya.
- Jika pekerjaan Anda belum 100% selesai, sudah jelas apa yang harus dilakukan.
Contoh yang baik tentang cara menggambarkan pekerjaan Anda
Anda tidak harus melakukan semua (atau sebagian) hal tersebut, tetapi ada beberapa cara yang dapat memenuhi persyaratan:
Buat postingan blog, halaman web, atau inti GitHub publik yang menjelaskan pekerjaan yang telah Anda lakukan dan link ke commit yang telah Anda buat dan repositori yang telah Anda kerjakan. Jika masih ada pekerjaan yang harus dilakukan pada proyek, sertakan deskripsi pekerjaan itu. Anda juga dapat membagikan sorotan atau bagian yang menantang.
Ini adalah opsi terbaik karena memungkinkan Anda untuk menyertakan banyak informasi dengan mudah. Ini bagus karena dengan jelas menunjukkan pekerjaan yang Anda lakukan, dan memudahkan orang lain untuk menggunakan serta memahami kontribusi Anda.
Jika menggunakan GitHub, dan semua pekerjaan dicakup oleh satu permintaan pull, Anda dapat menggunakan link tersebut.
- Pastikan deskripsi permintaan pull mendetail.
- Pastikan deskripsi menyatakan dengan jelas bahwa pekerjaan ditujukan untuk Musim Dokumen.
- Jika permintaan pull memerlukan lebih banyak upaya setelah Season Dokumen berakhir, pastikan komitmen Season terakhir Dokumen mencatat fakta ini.
- Metode memberikan laporan project ini memiliki manfaat berupa log perubahan, daftar commit, dan komentar ulasan di satu tempat.
Jika repositori GitHub Anda hanya memiliki satu tujuan untuk Season Dokumen, tambahkan file README yang berisi detail pekerjaan Anda.
Buat folder publik di Google Drive dan sertakan semua patch yang telah Anda buat.
Buat spreadsheet publik dengan Google Spreadsheet dan cantumkan semua commit Anda.
Tautkan ke satu masalah di Issue Tracker publik, yang berisi referensi yang jelas ke pekerjaan Anda dan hal lain yang sesuai. Masalah ini akan melacak semua pekerjaan yang telah Anda lakukan. Pastikan masalahnya mencantumkan semua commit atau commit dengan cara lain mudah ditemukan.
Tautkan ke perbedaan konteks atau terpadu dari perubahan Anda. Pastikan untuk menyertakan {i>header<i} yang menyertakan nama proyek penulisan teknik dan siapa Anda, sehingga berguna bagi orang lain.
Contoh yang buruk tentang cara menggambarkan pekerjaan Anda
Jangan lakukan hal-hal ini:
- Tautkan ke file tarball atau zip yang berisi seluruh kode sumber project atau direktori kerja Anda.
- Tautkan ke bagian atas repositori sumber utama project. Misalnya, jika Anda menangani cpython, link ini tidak berguna: https://github.com/python/cpython.
- Tautkan ke clone repositori sumber project Anda. Hal ini menyulitkan untuk melihat perubahan yang Anda buat karena karya Anda dicampur dengan karya orang lain.
- Link ke deskripsi project Anda di situs Season Dokumen.
Untuk mentor
Bantu penulis teknis Anda membuat laporan proyek yang tepat. Penting untuk melakukannya sebelum Anda membuat evaluasi sendiri atas karya penulis teknis.
Periksa hal-hal berikut:
- Kiriman harus memenuhi persyaratan yang dijelaskan di atas.
- Pengiriman harus menyertakan deskripsi pekerjaan yang telah dilakukan, persyaratan yang dipenuhi, dan alasan untuk keputusan tertentu yang diambil.
Gagasan tentang Season Dokumen bukanlah karena penulis teknis membuat banyak dokumentasi. Pekerjaan ini harus berpotensi berguna untuk proyek {i>open source<i} hosting.