Disiplin sitasi

Spec: ISO/IEC/IEEE 26514Spec: ISO 24495-1

Sekilas

Ini adalah halaman yang dirujuk oleh bagian Insider_ lain setiap kali menjelaskan bagaimana ia menyitasi sebuah standar. Halaman ini menjelaskan mengapa dokumentasi ini memparafrasekan spesifikasi alih-alih mengutipnya, bagaimana sebuah klaim menyebut standar dan klausa persis yang menjadi sandarannya, serta apa yang dijanjikan maupun tidak dijanjikan oleh sebuah sitasi yang bersih.

Halaman ini ditulis untuk insinyur senior yang ingin mengetahui aturan yang dipakai untuk menyusun sebuah klaim sebelum memercayainya — dan memang semestinya demikian.

Mengapa hal ini penting

Setiap halaman Insider_ lain membuat klaim dan menautkannya ke standar dan klausa yang disebut namanya. Sitasi itu hanya bernilai jika disiplin di baliknya bersifat eksplisit. Jika “didukung standar” bisa berarti apa saja, mulai dari “saya membaca spesifikasinya dengan cermat” hingga “saya kurang lebih ingat isinya”, maka sitasi itu hanya hiasan.

Ada pula kendala yang lebih berat. Banyak dokumen yang menjadi acuan NextPDF — spesifikasi ISO, ETSI, dan sejenisnya — berlisensi. Mereproduksi teksnya, sepanjang apa pun, tidak diizinkan. Karena itu, disiplin ini harus memecahkan dua masalah sekaligus: membuat sebuah klaim dapat dilacak ke sumbernya, tanpa mereproduksi sumber tersebut. Sebuah sitasi yang tepat dan parafrase yang setia menjawab keduanya, dan halaman ini adalah spesifikasinya.

Versi singkat

Insider_ memparafrasekan standar dan tidak pernah mengutip standar berlisensi. Sebuah klaim menyebut standar dan klausa yang persis; klaim itu tidak mereproduksi kata-kata standar tersebut.
Parafrase bukan jalan pintas; ia adalah uji pemahaman. Menyatakan ulang sebuah persyaratan dengan gaya bahasa NextPDF sendiri memaksa penulis untuk memahaminya, sekaligus menjaga terminologi tetap konsisten dengan glosarium Spec: ISO/IEC/IEEE 26514, §8.
Setiap klaim yang didukung standar menyebut klausa atau bagian yang spesifik, bukan seluruh dokumen, sehingga peninjau berikutnya dapat membuka klausa itu dan mengonfirmasi parafrasenya terhadap klausa tersebut.
Sebuah sitasi menyebutkan jenis sumber yang menjadi sandarannya — sebuah klausa, kode mesin, sebuah tes, sebuah pengukuran — sehingga klaim berlebih langsung terlihat sekilas.
Ketika sebuah klaim tidak dapat ditautkan ke klausa yang benar-benar telah dibaca penulis, klaim tersebut tidak dipalsukan. Klaim itu tetap dipertahankan, ditandai belum terselesaikan, dan halaman tetap tidak diterbitkan — sebuah protokol yang terdokumentasi, bukan improvisasi.

Bagaimana NextPDF menanganinya

Parafrase, bukan kutipan

Aturan paling ketat dalam hierarki gaya NextPDF mengesampingkan setiap panduan hulu: tidak ada teks verbatim dari badan standar berlisensi, sependek apa pun kutipannya. Sebagai gantinya, sebuah halaman menyebut standar dan klausanya serta memparafrasakan persyaratan dengan suaranya sendiri.

Hal ini biasanya dibingkai sebagai kendala lisensi, dan memang demikian. Pembingkaian yang lebih berguna bersifat editorial. Kutipan verbatim hanya membuktikan bahwa Anda bisa menyalin. Parafrase yang setia menunjukkan bahwa Anda memahami klausa itu cukup baik untuk menyatakannya ulang tanpa mengubah maknanya. Hal ini juga menjaga kalimat tetap berada dalam kosakata NextPDF yang konsisten, alih-alih beralih gaya di tengah halaman, sebagaimana yang dituntut oleh model kualitas dokumentasi Spec: ISO/IEC/IEEE 26514, §8. Bahasa yang lugas dinilai dari apakah pembaca dapat menemukan, memahami, dan menggunakan kontennya, bukan dari apakah prosanya mencerminkan sumber Spec: ISO 24495-1, §Introduction; parafrase mendukung tujuan itu, kutipan tidak.

Sebuah klaim menyebut klausa, bukan sekadar dokumennya

Mekanisme yang membuat sebuah parafrase dapat diperiksa adalah ketepatan. Setiap klaim yang didukung standar menyebut klausa atau bagian persis yang menjadi sandarannya — misalnya ISO 32000-2 §6 — bukan sekadar dokumennya. Peninjau tidak perlu memercayai ingatan penulis; mereka membuka klausa itu dan membandingkannya dengan pernyataan ulang. Acuan klausa adalah penghubung antara sumber yang tidak boleh dikutip dan klaim yang dapat diverifikasi. Ia menunjukkan di mana harus melihat tanpa membawa teks sumber itu sendiri.

Sebuah sitasi menyatakan jenis sumbernya

Sitasi menjawab “dari mana”. Ia juga harus menjawab “jenis apa”. Menyebut bahwa sebuah klaim bersandar pada klausa sebuah standar adalah janji yang berbeda dari menyebut bahwa ia bersandar pada kode mesin itu sendiri, pada sebuah tes, atau pada sebuah pengukuran. NextPDF menjaga jenis-jenis itu tetap terpisah agar pembaca dapat menimbangnya: kode dan tes berada di atas perilaku runtime, runtime di atas metadata, dan metadata di atas prosa. Halaman editorial seperti halaman ini tidak berpura-pura didukung kode.

Jenis sumber	Apa yang dijanjikannya	Apa yang tidak dijanjikannya
Didukung kode	Klaim diperiksa terhadap kode sumber mesin atau contoh yang dapat dijalankan	Bahwa suatu standar mewajibkannya
Didukung standar	Klaim ditambatkan ke klausa yang disitasi dan diparafrasakan	Bahwa kode saat ini mengimplementasikannya tanpa kecuali
Didukung tes	Sebuah tes dalam suite menjaga perilaku tetap pada tempatnya	Sebuah angka performa
Didukung tolok ukur	Pengukuran dengan metode yang dinyatakan mendukung angka tersebut	Angka yang sama pada perangkat keras Anda
Didukung artefak	Sebuah artefak yang dihasilkan (keluaran build, sebuah laporan) memperagakannya	Sebuah mandat standar
Prinsip desain	Sebuah keputusan desain yang disengaja dan beralasan	Sebuah pengukuran empiris
Editorial	Sebuah penjelasan beralasan yang menata materi lain	Sebuah jaminan perilaku baru tersendiri
Campuran	Halaman memadukan beberapa basis dan menyebutkan basis mana untuk tiap klaim	Sebuah basis tunggal yang bersih

Halaman ini bersifat editorial: ia tidak menegaskan perilaku mesin apa pun. Halaman ini menjelaskan disiplin yang menjadi sandaran sitasi di halaman-halaman lain. Itulah basis yang jujur bagi halaman ini, dan menyatakannya adalah penerapan disiplin terhadap dirinya sendiri.

Ketika sumber tidak dapat dibaca

Akses ke sebuah standar tidak selalu langsung tersedia — sebuah spesifikasi berlisensi mungkin masih harus diperoleh penulis, atau sebuah klausa mungkin perlu dibaca kedua kalinya sampai maknanya jelas. Integritas disiplin ini terlihat dari apa yang terjadi pada saat itu. Penulis tidak menebak. Sebuah klaim yang belum dapat ditautkan ke klausa yang benar-benar telah dibaca penulis tetap dipertahankan, dilampirkan ke materi dalam repositori dan acuan standar yang dideklarasikan oleh kode itu sendiri, secara eksplisit ditandai belum terselesaikan, dan halaman tetap tidak diterbitkan sampai klausa itu disitasi dengan benar.

Langkah-langkah terlarang dijabarkan dan dapat diperiksa: nomor klausa yang dibuat-buat agar tampak persis, sitasi yang didandani seolah-olah telah dibaca padahal ditulis dari ingatan, atau menghapus klaim secara diam-diam untuk menghindari sitasi. Sitasi terbuka yang ditandai dengan benar pada sebuah draf adalah utang dengan sebuah catatan, bukan cacat. Pemeriksaan luring yang deterministik menegakkan pembedaan itu secara persis.

Contoh praktis

Disiplin ini konkret: bentuknya adalah struktur front-matter citations sebuah halaman. Setiap entri menautkan sebuah klaim ke klausanya.

citations:
  - spec: "ISO 32000-2"
    clause: "§6"
    # NextPDF-worded topic — the paraphrase, never the standard's text
    topic: "A writer's created or amended PDF elements must conform and stay consistent"

Tidak ada field quote, dan itu disengaja. topic adalah pernyataan ulang dalam gaya NextPDF sendiri. spec dan clause adalah cara peninjau kembali ke sumber yang persis untuk memeriksa pernyataan ulang itu. Entri itu membawa penunjuk ke klausa, bukan kata-kata klausanya.

Kesalahpahaman umum

Kesalahpahaman pertama adalah membaca “parafrasakan, jangan kutip” sebagai pengelakan — cara untuk terdengar berwibawa tanpa berkomitmen. Justru sebaliknya. Sebuah kutipan tidak berkomitmen apa pun; ia meminjam kata-kata orang lain. Sebuah parafrase yang disertai sitasi mengikat penulis pada pernyataan ulang yang dapat disanggah oleh peninjau terhadap klausanya. Disiplin ini membuat klaim lebih dapat dipertanggungjawabkan, bukan kurang.

Kesalahpahaman kedua adalah memperlakukan “editorial” sebagai tingkatan yang lebih lemah daripada “didukung standar”. Itu sama sekali bukan soal tingkatan; ia adalah jenis yang berbeda. Halaman editorial seperti halaman ini menata dan menjelaskan materi lain. Halaman ini dilabeli dengan benar. Dan label itulah intinya: sistem ini berhasil karena sebuah halaman memberi tahu Anda jenis sumber apa yang menjadi sandarannya sebelum Anda memutuskan seberapa besar bobot yang akan Anda berikan.

Batasan dan ruang lingkup

Halaman ini menetapkan disiplin sitasi; halaman ini bukan lembar gaya atau kode gerbang. Artefak yang berwenang berada dalam repositori (docs/style/nextpdf-overrides.md §5 dan skrip composer.jsondocs:*) dan menggantikan ringkasan apa pun di sini jika keduanya berbeda. Halaman ini tidak menegaskan perilaku mesin apa pun.

Disiplin ini mengikat klaim, bukan kesimpulan pembaca. Sebuah parafrase yang disitasi dengan setia memberi tahu Anda apa yang dituntut oleh sebuah klausa. Apakah pembacaan NextPDF merupakan pembacaan yang dibutuhkan oleh kewajiban Anda tetap menjadi keputusan Anda, dan itulah sebabnya halaman perilaku juga membawa sitasi yang didukung kode atau tes, bukan hanya didukung standar saja. Secara jujur, penegakannya masih sebagian: pemeriksaan luring sudah aktif, sementara verifikator kutipan verbatim dan sitasi langsung sudah terpasang sedangkan runner menyeluruhnya masih dalam penyelesaian — dinyatakan sebagai sedang berjalan, bukan sebagai selesai.

Dokumen terkait

Dokumentasi sebagai produk — disiplin kualitas yang lebih luas yang menjadi bagian dari sistem sitasi ini.
Lanskap standar — standar yang dirujuk oleh sitasi-sitasi ini, dan bagaimana sebuah klausa menjadi perilaku yang terdokumentasi.
Piramida pengujian NextPDF — apa arti bukti yang didukung tes ketika sebuah halaman bersandar pada basis itu, bukan basis halaman ini.

Glosarium

Disiplin sitasi — himpunan aturan yang mengatur bagaimana sebuah klaim Insider_ ditautkan ke sumbernya: memparafrasekan, menyebut klausa yang persis, tidak pernah mengutip standar berlisensi.
Parafrase — pernyataan ulang sebuah persyaratan dengan gaya bahasa NextPDF sendiri yang konsisten dengan glosarium; uji pemahaman yang menggantikan kutipan.
Acuan klausa — klausa atau bagian persis yang menjadi sandaran sebuah parafrase, dicatat agar peninjau dapat membukanya dan memverifikasi pernyataan ulang.
Klaim yang didukung standar — sebuah klaim yang ditambatkan ke klausa yang disitasi dan diparafrasakan dari standar yang disebut namanya, berbeda dari klaim yang bersandar pada kode mesin, sebuah tes, sebuah pengukuran, atau penalaran editorial.
Sitasi belum terselesaikan — sebuah klaim yang belum dapat ditautkan ke klausa yang telah dibaca penulis; tetap dipertahankan, ditandai terbuka, dan ditahan dari publikasi alih-alih dipalsukan.