KAL
Menu

Menuliskannya

Menulis penjelasan yang mengajarkan orang lain.

Daftar isi

Dokumen portofolio bernilai penuh hanya ketika tulisannya mengajarkan pembaca mengulang seluruh prosesnya. Topik ini membahas teknik menulis penjelasan untuk proyek matematika yang sudah dikerjakan dan terverifikasi, mulai dari profil pembaca, kerangka dokumen, gaya kalimat yang mengajarkan, demo yang dapat dicoba langsung, sampai cara memeriksa dokumen seperti memeriksa kode. Hasil akhirnya adalah dokumen yang dapat dijalankan ulang oleh pembaca mana pun tanpa bantuan penulisnya.

Pembaca yang dituju dan kebutuhannya#

Dokumen portofolio ditulis untuk pembaca yang mengenal Python tetapi belum mempelajari materinya, misalnya rekan sejawat dari tim lain atau pembaca kode yang menilai portofolio. Pembaca semacam ini membutuhkan empat jawaban yang wajib tersedia di dalam dokumen, yaitu masalah apa yang diselesaikan, model matematika apa yang dipilih, alasan hasilnya dapat dipercaya, dan perintah persis untuk menjalankannya ulang. Dokumen yang salah satu jawabannya hilang memaksa pembaca membaca ulang seluruh kode, dan kondisi itu berarti dokumen gagal menjalankan tugasnya.

Gaya yang cocok adalah gaya dokumentasi resmi, sebagaimana gaya penulisan jalur ini, yaitu impersonal, presisi, dan sistematis. Instruksi ditulis sebagai kalimat perintah, fakta dinyatakan langsung tanpa sapaan, dan setiap istilah baru diperkenalkan sekali dengan penjelasan singkat sebelum digunakan bebas. Nada promosi tidak diperlukan karena keluaran terverifikasi sudah menyatakan kualitasnya. Kalimat yang memuji hasil tanpa menunjukkan angkanya dibuang, sedangkan kalimat yang menyebut angka disertai tempat angka itu berasal.

Kerangka lima bagian#

Kerangka berikut digunakan untuk setiap dokumen proyek karena urutan bagiannya mengikuti pertanyaan pembaca dari atas ke bawah. Isinya sengaja tidak memuat materi proyek tertentu, sehingga templat yang sama dapat digunakan untuk analisis dadu maupun pencari rute. Salinlah berkasnya, lalu isi setiap bagian dengan materi proyek yang sudah selesai dikerjakan dan diverifikasi.

markdown kerangka-portofolio.md 
<!-- Kerangka dokumen portofolio. Salin berkas ini, lalu isi setiap bagian untuk proyek baru. -->
# <Nama Proyek>

## Masalah yang diselesaikan
Satu paragraf yang menyebut data yang dipakai, besaran yang dihitung, dan angka akhirnya.

## Model matematika
Rumus model beserta arti setiap simbolnya, ditulis dengan notasi matematika.

## Verifikasi
Setiap uji beserta metode pembandingnya dan hasil `np.allclose` yang tercetak.

## Cara menjalankan
Perintah persis untuk mereproduksi hasil, dijalankan dari folder proyek.

## Keterbatasan
Cakupan yang tidak dijamah model dan perilaku yang perlu diwaspadai.

Bagian masalah menyebut data, besaran yang dihitung, dan angka akhirnya dalam satu paragraf, sehingga pembaca yang terburu-buru tetap membawa hasil utamanya. Bagian model menuliskan rumus beserta arti setiap simbolnya, dan bagian verifikasi mencantumkan uji beserta hasil np.allclose-nya apa adanya. Bagian cara menjalankan hanya berisi perintah persis dari folder proyek, sedangkan bagian keterbatasan menyatakan cakupan yang tidak dijamah model, misalnya data yang hanya berasal dari satu rumah. Susunan ini membuat dokumen dapat dibaca bertingkat, dari paragraf masalah saja sampai menjalankan ulang seluruh proyek.

Gaya kalimat yang mengajarkan#

Kalimat yang mengajarkan memiliki ciri yang dapat diperiksa, dan daftar berikut merangkum cirinya untuk diterapkan pada setiap bagian dokumen.

  • Kalimat pertama setiap bagian menyatakan inti teknisnya, bukan pengantar yang menunda.
  • Setiap klaim numerik disertai keluaran asli dari kode yang dapat dijalankan ulang.
  • Rumus ditulis dengan notasi matematika, sedangkan kode tetap berada di blok kode.
  • Instruksi berbentuk kalimat perintah tanpa sapaan dan tanpa kata ganti persona.
  • Istilah baru diperkenalkan sekali dengan penjelasan singkat sebelum digunakan lagi.
  • Satu paragraf mengembangkan satu gagasan dalam tiga sampai lima kalimat.

Butir-butir di atas menerapkan kebiasaan menulis jalur ini pada dokumen proyek. Frasa yang tidak membawa isi, seperti perumpamaan yang tidak menjelaskan mekanisme, dibuang, dan kalimat yang memaksa pembaca menerjemahkannya kembali ke kode ditulis ulang. Dokumen yang lolos daftar ini terbaca seperti dokumentasi resmi dan bukan catatan pribadi penulisnya, sehingga setiap kalimatnya memuat fakta, rumus, perintah, atau rujukan keluaran.

Demo yang dapat dicoba pembaca#

Dokumen portofolio proyek regresi menyematkan demo berikut. Geser slider jam AC untuk membaca prediksi model pada nilai pemakaian mana pun, kemudian amati titik merah bergerak sepanjang garis model di antara titik-titik data pencatatan. Setiap langkah slider berukuran seperempat jam, sehingga nilai antara seperti 7.75 jam dapat dicoba dengan cepat. Pada posisi nol jam, prediksi bertepatan dengan beban dasar rumah, dan makin ke kanan, sumbangan per jam AC makin besar.

Kode sumber demo
<!DOCTYPE html>
<html lang="id">
<head>
<meta charset="utf-8">
<title>Prediksi konsumsi list dari jam AC</title>
<style>
  body { font-family: sans-serif; margin: 12px; color: #241f31; }
  .baris { display: flex; align-items: center; gap: 10px; margin: 8px 0; flex-wrap: wrap; }
  input[type="range"] { width: 200px; }
  #peta { background: #f6f5f4; border-radius: 6px; }
  #status { margin-top: 8px; padding: 10px 12px; border-radius: 6px; background: #f6f5f4; }
</style>
</head>
<body>
  <div class="baris">
    <label for="jam">jam AC = <span id="vjam">8.00</span></label>
    <input id="jam" type="range" min="0" max="12" step="0.25" value="8">
  </div>
  <canvas id="peta" width="420" height="280"></canvas>
  <div id="status"></div>
<script>
  // koefisien model, sama dengan isi berkas hasil_model.txt
  var W0 = 3.27101578;
  var W1 = 0.84556299;
  // data pencatatan tiga puluh hari, sama dengan data_konsumsi.csv
  var data = [
    [9.4, 11.94], [5.4, 7.65], [10.3, 11.78], [8.5, 10.14], [1.4, 4.61],
    [11.7, 13.54], [9.2, 10.98], [9.5, 10.98], [1.8, 4.44], [5.6, 8.19],
    [4.6, 7.37], [11.1, 12.83], [7.8, 9.60], [9.9, 11.70], [5.5, 7.92],
    [3.0, 5.83], [6.8, 9.29], [1.0, 4.13], [10.0, 11.94], [7.7, 9.77],
    [9.2, 11.12], [4.4, 7.16], [11.7, 12.63], [10.7, 12.18], [9.4, 11.03],
    [2.6, 5.19], [5.8, 8.03], [0.8, 4.40], [2.1, 4.68], [8.3, 10.59]
  ];
  var kiri = 46, bawah = 34, atas = 14;
  var lebarX = 420 - kiri - 14;   // piksel untuk rentang sumbu x
  var tinggiY = 280 - atas - bawah;
  var XMAKS = 13, YMAKS = 15;

  function px(x) { return kiri + x * lebarX / XMAKS; }
  function py(y) { return 280 - bawah - y * tinggiY / YMAKS; }

  function gambar() {
    var kanvas = document.getElementById("peta");
    var ctx = kanvas.getContext("2d");
    ctx.clearRect(0, 0, kanvas.width, kanvas.height);

    // sumbu x dan y
    ctx.strokeStyle = "#c9c5c1";
    ctx.beginPath();
    ctx.moveTo(kiri, atas);
    ctx.lineTo(kiri, 280 - bawah);
    ctx.lineTo(420 - 14, 280 - bawah);
    ctx.stroke();
    ctx.fillStyle = "#77767b";
    ctx.font = "11px sans-serif";
    ctx.fillText("jam AC", 420 - 60, 280 - 12);
    ctx.fillText("kWh", 8, atas + 10);
    for (var t = 0; t <= 12; t += 4) {
      ctx.fillText(String(t), px(t) - 4, 280 - bawah + 14);
    }

    // garis model dari x = 0 sampai x = 13
    ctx.strokeStyle = "#1a5fb4";
    ctx.lineWidth = 2;
    ctx.beginPath();
    ctx.moveTo(px(0), py(W0));
    ctx.lineTo(px(13), py(W0 + 13 * W1));
    ctx.stroke();
    ctx.lineWidth = 1;

    // titik data pencatatan
    ctx.fillStyle = "#9a9996";
    for (var i = 0; i < data.length; i++) {
      ctx.beginPath();
      ctx.arc(px(data[i][0]), py(data[i][1]), 3, 0, 2 * Math.PI);
      ctx.fill();
    }

    // titik prediksi sesuai posisi slider
    var jam = parseFloat(document.getElementById("jam").value);
    var pred = W0 + W1 * jam;
    ctx.beginPath();
    ctx.arc(px(jam), py(pred), 5, 0, 2 * Math.PI);
    ctx.fillStyle = "#c01c28";
    ctx.fill();

    document.getElementById("vjam").textContent = jam.toFixed(2);
    document.getElementById("status").textContent =
      "prediksi = " + pred.toFixed(2) + " kWh = beban dasar " + W0.toFixed(2) +
      " + sumbangan AC " + (W1 * jam).toFixed(2);
  }

  document.getElementById("jam").addEventListener("input", gambar);
  gambar();
</script>
</body>
</html>

Demo menggunakan koefisien yang persis sama dengan isi berkas hasil_model.txt, yaitu 3.27101578 dan 0.84556299, sehingga angka yang dibaca pembaca konsisten dengan seluruh dokumen. Titik kelabu pada kanvas adalah data pencatatan tiga puluh hari yang sama dengan isi berkas data_konsumsi.csv. Kode sumber demonya dapat dibuka melalui tampilan kode di sampingnya, sehingga pembaca yang ingin meniru polanya cukup menyalin bagian yang dibutuhkan. Konsistensi semacam ini penting karena demo yang angkanya berbeda dari dokumennya justru meruntuhkan kepercayaan yang sedang dibangun portofolio.

Memeriksa dokumen seperti memeriksa kode#

Dokumen diverifikasi dengan cara yang sama seperti kodenya. Pemeriksaan dilakukan dengan menyalin proyek ke folder kosong, menjalankan persis perintah pada bagian cara menjalankan, lalu membandingkan keluarannya dengan angka yang tertulis di dokumen. Folder dokumen ini menyimpan dua berkas inti proyek, yaitu konsumsi_listrik.py dan data_konsumsi.csv yang isi dan penjelasannya dibahas pada topik pengerjaan dalam modul ini, sehingga perintah berikut dapat dijalankan langsung dari folder topik.

bash 
# uji dokumen: salin proyek ke folder kosong dan jalankan perintahnya
mkdir -p /tmp/uji-dokumen
cp konsumsi_listrik.py data_konsumsi.csv /tmp/uji-dokumen/
cd /tmp/uji-dokumen
python3 konsumsi_listrik.py
text Keluaran 
jumlah hari data  : 30
intersep w0       : 3.2710 kWh
koefisien w1      : 0.8456 kWh per jam AC
residual RMS      : 0.2768 kWh
prediksi 8 jam AC : 10.0355 kWh

Keluaran pada folder kosong sama persis dengan angka yang dikutip dokumen, sehingga bagian cara menjalankan lolos pemeriksaan. Apabila keluarannya berbeda, salah satu dari dua hal sedang terjadi, yaitu dokumen mengutip angka lama atau kodenya berubah tanpa revisi dokumen. Keduanya wajib diperbaiki sebelum portofolio dibagikan karena satu angka yang tidak terulang cukup untuk meragukan seluruh dokumen.

Ringkasan#

  • Dokumen portofolio ditulis untuk pembaca yang mengenal Python tetapi belum mempelajari materinya, dengan gaya dokumentasi resmi yang impersonal.
  • Kerangka lima bagian, yaitu masalah, model, verifikasi, cara menjalankan, dan keterbatasan, menjawab pertanyaan pembaca secara berurutan.
  • Setiap klaim numerik disertai keluaran asli, dan perintah di dalam dokumen diuji ulang di folder kosong seperti kode.
  • Demo interaktif menempatkan intuisi di depan dengan koefisien yang identik dengan model tersimpan.

Referensi#