3 skrip shell untuk menemukan weasel words, kalimat pasif, dan kata berulang

• Dalam penulisan teknis, kelemahan yang berulang bisa lebih dulu diungkap lewat pemeriksaan otomatis daripada selalu ditunjukkan satu per satu oleh manusia; artikel ini memperkenalkan 3 skrip shell yang dapat dipasang ke build makalah LaTeX
• Tujuannya bukan melarang kalimat pasif atau ekspresi tertentu, melainkan membuat penulis melihat kalimat yang ditandai dan memilih ungkapan yang lebih jelas dan akurat
• Weasel words seperti various, quite, surprisingly, very, extremely mengaburkan presisi, sehingga dideteksi dengan regex untuk mempersempit titik yang perlu ditinjau
• Pemeriksaan kalimat pasif mencari bentuk -ed setelah verba be atau participle tak beraturan, sementara pemeriksaan kata berulang menangkap kata yang sama secara bersebelahan tanpa membedakan huruf besar-kecil
• Jika ketiga pemeriksaan digabung lewat make proof, semuanya dapat dijalankan berulang di dalam repositori makalah dan mengurangi kemungkinan kesalahan kecil menumpuk hingga terbaca sebagai kurang penyuntingan akhir

---

Mengurangi kelemahan menulis yang berulang dengan otomatisasi

• Dalam membimbing mahasiswa Ph.D., bagian yang sangat sulit adalah mengajarkan menulis, dan masalah yang muncul berulang dapat disaring lebih dulu dengan alat
• Tiga masalah yang disasar skrip ini adalah sebagai berikut
  • Penyalahgunaan kalimat pasif
  • weasel words
  • lexical illusion, yaitu kata berulang yang mudah luput dari penglihatan
• Skrip-skrip ini digunakan dengan mengintegrasikannya ke sistem build dokumen LaTeX
• Karena aturan menulis memiliki pengecualian, tujuannya bukan melarang struktur tata bahasa tertentu
• Ketika sebuah kalimat disorot, penulis terdorong memeriksa sendiri: “apakah ada ungkapan yang lebih jelas dan presisi?”
• Jika Anda programmer, Anda bisa mengenali kelemahan berulang sendiri dan memanfaatkan otomatisasi untuk menguranginya

Buku yang bisa dijadikan rujukan untuk penulisan teknis

• The Elements of Style tidak sempurna, tetapi masih berguna sebagai rujukan gaya
  • Bacalah dengan mempertimbangkan kritik dari para ahli linguistik
  • Dalam tulisan sains, teknik, dan matematika, ketiadaan gaya kadang terlihat sangat mencolok
• Style: The Basics of Clarity and Grace, setelah direkomendasikan oleh Zachary Tatlock, dinilai sebagai rujukan yang lebih baik daripada Strunk and White
  • Jika harus memilih satu buku saja, buku ini layak dipilih
• The Chicago Manual of Style dipakai sebagai standar untuk mengakhiri perdebatan gaya
• A Manual for Writers of Research Papers, Theses, and Dissertations merupakan padanan manual Chicago untuk penulisan teknis

Titik tempat presisi dan kejelasan bocor

• Olin Shivers mengajarkan penulisan teknis sebagai keseimbangan antara presisi, kejelasan, dan pemasaran
• Dalam proses pengajuan makalah, terlihat titik-titik tempat presisi dan kejelasan melemah dengan cara yang dapat diidentifikasi secara mekanis
  • weasel words
  • Penyalahgunaan kalimat pasif
• Sulit membuat skrip shell yang juga bisa menangkap pemasaran yang buruk atas ide ilmiah

Mendeteksi weasel words

• Weasel words adalah kata atau frasa yang tampak bagus tetapi hampir tidak menyampaikan informasi, sehingga mengaburkan presisi kalimat
• Weasel words yang sering terlihat dalam tulisan mahasiswa terbagi menjadi tiga jenis

• Salt and pepper words

  • Mahasiswa pascasarjana baru kadang menaburkan kata-kata yang tampak teknis seperti bumbu ke dalam kalimat, tetapi tidak benar-benar menyampaikan informasi
  • Contoh utamanya adalah various, a number of, fairly, quite
  • Menghapus kata-kata seperti ini membuat kalimat lebih kuat
  • It is quite difficult to find untainted samples. → It is difficult to find untainted samples.
  • We used various methods to isolate four samples. → We isolated four samples.

• Beholder words

  • Beholder words adalah kata yang maknanya berubah tergantung pembacanya
  • Contohnya interestingly, surprisingly, remarkably, clearly
  • Peer reviewer tidak menyukai ungkapan yang seolah mengambil alih penilaian untuk mereka
  • Daripada False positives were surprisingly low., lebih baik menampilkan angka dan pihak yang mengamati, seperti To our surprise, false positives were low (3%).

• Lazy words dan adverbia

  • Lazy words adalah kata yang dipakai untuk menghindari penyajian karakteristik kuantitatif, sehingga sains terlihat kurang kokoh dan belum selesai
  • Contoh terburuknya adalah very dan extremely, yang sulit diterima dalam penulisan teknis
  • Contoh lain adalah several, exceedingly, many, most, few, vast
  • Dalam penulisan teknis, adverbia cenderung terlihat seperti weasel words
  • Dalam penulisan teknis mahasiswa pascasarjana baru, menghapus semua adverbia kemungkinan besar memberi dampak bersih yang positif
  • We offer a completely different formulation of CFA. lebih baik menjadi We offer a different formulation of CFA.

• Skrip weasel words

  • Skrip Bash mendefinisikan daftar weasel words dasar sebagai regex, lalu menandai lokasinya dalam file input dengan egrep -i -n --color
  • Jika daftar dasar tidak cocok, file daftar pengganti dapat digunakan
    • $HOME/etc/words/weasels
    • $WORDSDIR/weasels
    • words/weasels
  • Jika tidak ada argumen, skrip menampilkan cara pakai dalam bentuk usage: <script> <file> ...

Menangani kalimat pasif secara sadar

• Dalam penulisan teknis, kalimat pasif tidak selalu buruk
• Namun, lebih dari separuh tulisan teknis yang pernah diedit dapat diperbaiki hanya dengan menghapus kalimat pasif
  • Mahasiswa lebih sering menyalahgunakan kalimat pasif daripada menggunakannya dengan baik
• Kalimat pasif menjadi masalah ketika menyembunyikan informasi yang relevan atau deskriptif
  • Termination is guaranteed on any input. menyembunyikan informasi yang relevan
  • Termination is guaranteed on any input by a finite state-space. memasukkan informasi yang relevan, tetapi penekanannya meleset
  • A finite state-space guarantees termination on any input. memuat informasi yang relevan dan lebih tajam
• Ketika subjek benar-benar tidak penting, kalimat pasif bisa lebih baik
  • 4 mL HCl were added to the solution.
  • Namun We added 4 mL HCl to the solution. juga tidak dianggap sebagai masalah serius

• Pertanyaan untuk menilai kalimat pasif

  • Ketika skrip menandai kalimat pasif, periksalah dua hal
    • Apakah pelaku relevan tetapi tidak jelas?
    • Apakah tulisan akan lebih enak dibaca jika diubah ke kalimat aktif?
  • Jika jawaban untuk keduanya “ya”, ubahlah menjadi kalimat aktif
  • Jika hanya pertanyaan pertama yang “ya”, sebutkan pelakunya secara eksplisit

• Skrip kalimat pasif

  • Skrip Bash mendefinisikan daftar panjang past participle tak beraturan
  • Skrip mencari pola berupa spasi dan \w+ed atau participle tak beraturan setelah am|are|were|being|is|been|was|be
  • Skrip menandai hasil dengan egrep -n -i --color, termasuk nama file dan nomor baris

Kata berulang dan lexical illusion

• Jika ada pergantian baris, kata berulang seperti the the mudah luput dari mata
• Dengan hanya mengubah pergantian baris, pengulangan yang sama bisa terlihat lebih jelas
• Pengulangan kata adalah fenomena yang muncul dalam proses penulisan dokumen elektronik, dan tampak seperti akibat kesalahan potong-tempel
• Ini sering terjadi terutama pada the
• Satu kata berulang saja tidak akan membuat makalah ditolak, tetapi jika kesalahan kecil seperti typo dan kata berulang menumpuk, kurangnya penyuntingan akhir akan terlihat
• Reviewer dapat menafsirkan kurangnya penyuntingan akhir sebagai kurangnya penghargaan terhadap waktu dan perhatian mereka

• Skrip kata berulang

  • Skrip Perl mencari kata berulang yang bersebelahan
  • Skrip membaca file baris demi baris dan memecahnya berdasarkan karakter non-kata
  • Spasi dilewati, dan ketika menemukan tanda baca, status kata terakhir direset
  • Jika kata saat ini dan kata sebelumnya sama setelah dibandingkan dalam huruf kecil, skrip mencetak dalam format nama_file:nomor_baris kata
  • Kode keluar adalah jumlah pengulangan yang ditemukan

Mengintegrasikan ke Makefile

• Simpan salinan lokal skrip di direktori bin/ pada setiap repositori makalah
• Tambahkan aturan make proof ke Makefile
• make proof menjalankan tiga pemeriksaan secara berurutan terhadap file *.tex
  • sh bin/weasel *.tex
  • sh bin/passive *.tex
  • perl bin/dups *.tex

Pemasaran makalah dan peer review

• Mahasiswa pascasarjana pada awalnya mudah berpikir bahwa menulis seluruh kebenaran saja sudah cukup untuk diterbitkan
• Namun ada banyak hal yang benar, dan di venue peer review papan atas pun sudah ada banyak makalah yang secara teknis benar
• Peer review telah menjadi lebih mirip proses menentukan kebenaran mana yang layak diketahui
• Dari sudut pandang ini, reviewer adalah penjaga perhatian kolektif, sumber daya komunitas ilmiah yang paling terbatas
• Untuk memasarkan makalah, penulis harus menunjukkan secara meyakinkan bahwa idenya layak mendapat akses ke sumber daya tersebut

Alat terkait dan ide perluasan

• Benjamin Beckwith terinspirasi oleh skrip ini dan membuat mode "writegood" untuk Emacs
• John Regehr mengusulkan skrip sederhana untuk menangkap frasa yang tidak perlu seperti Note that, Notice that
• Orang lain mengusulkan skrip untuk menangkap penggunaan future tense dalam penulisan teknis

[GN⁺]

Komentar Hacker News

• Saat menulis makalah, materi yang membantu memperbaiki tulisan adalah How to Write Mathematics karya Paul R. Halmos dan Mathematical Writing karya Donald E. Knuth dkk.
  Untuk menangkap rasa komunikasi yang jelas dan akurat, saya biasanya mulai dengan membaca Halmos, dan saran “Bad/Better/OK” mengingatkan pada pembahasan yang saya lihat di catatan kuliah Knuth dkk.
  Sebagai tahap ketiga, linter seperti yang diusulkan bisa berguna untuk menangkap bagian yang terlewat.
  Bagi siapa pun yang menulis tentang topik yang sedikit saja melibatkan definisi, materi seperti ini menurut saya wajib.

  • Selain rekomendasi itu, The Craft of Scientific Writing karya M. Alley juga bagus.

• Jika Anda menyukai tulisan ini dan ingin tahu lebih jauh tentang proses penulisan disertasi PhD yang efektif, ada baiknya melihat [1].
  Sebenarnya siapa pun yang ingin meningkatkan kemampuan komunikasi layak menontonnya, dan bahkan kalau saya harus membayar untuk mengakses video ini pun rasanya tidak akan rugi.
  [1] https://youtu.be/vtIzMaLkCaM

  • Akan bagus kalau ada repositori yang mengumpulkan “semua hal yang perlu diketahui saat memulai program PhD”.
    Termasuk materi terkenal seperti phd grind.

• Saya sulit setuju dengan banyak contohnya.
  Misalnya, jika “It is quite difficult to find untainted samples” diubah menjadi “It is difficult to find untainted samples”, quite difficult dan sekadar difficult terbaca cukup berbeda.
  Kalimatnya bukan menjadi lebih baik; maknanya berubah.
  Selain itu, fakta bahwa seseorang menulis “various methods” adalah informasi bahwa metodenya tidak tunggal, tetapi informasi itu hilang di kalimat kedua.

  • Makna yang disampaikan “quite” bisa sangat bervariasi tergantung pembaca atau konteks.
    Dalam ujaran, maknanya banyak berubah tergantung intonasi; secara ketat lebih dekat ke “agak sulit”, tetapi di banyak tempat juga dipakai seperti “hampir mustahil”.
    Saya tidak menganggap menghapus kata itu salah, tetapi menurut saya lebih baik menggantinya dengan ungkapan perbandingan yang lebih spesifik.
  • Karena hal seperti inilah akhirnya kita membaca dokumen desain 30 halaman untuk sesuatu yang bisa disampaikan dalam 3 halaman.
    Ada baiknya mencoba memahami mengapa orang begitu membenci tulisan yang dekoratif, terutama dalam dokumentasi teknis.
    Jika banyak membaca makalah atau desain, gaya seperti itu membuat hidup terasa menyiksa.
  • Jika ingin mengatakan bahwa metode yang berbeda digunakan, tuliskan saja apa yang sebenarnya dilakukan.
    Lebih jelas jika menulis seperti “We isolated four samples using the following methods…”.
  • Sebagian besar contohnya tampak buruk.
    Ini adalah salah satu alasan mengapa makalah sulit dibaca bahkan ketika menyampaikan hal yang sederhana.
    Orang terpaku pada gaya formal yang kaku dan tidak disukai siapa pun, sambil membuang petunjuk konteks yang halus tetapi penting.

• Jika mencari alat lain seperti ini, vale.sh layak dicoba.
  Anda bisa menambahkan berbagai pedoman gaya, termasuk menghindari kata-kata ambigu.
  GitHub Action yang dipakai untuk menjalankan vale pada situs web saat PR ada di sini: https://github.com/FusionAuth/fusionauth-site/blob/main/.git...
  Konfigurasinya ada di sini: https://github.com/FusionAuth/fusionauth-site/tree/main/conf...
  Ini membantu menegakkan gaya, tetapi kemungkinan kami belum memanfaatkan fiturnya secara maksimal.

  • Vale.sh terlihat cukup bagus.
    Saat ini saya sedang menyunting edisi ke-3 sebuah buku dan beberapa tulisan situs web, jadi sepertinya bisa berguna.

• Saya meminta Claude memindahkan skrip Bash itu ke UI web, sehingga kode bisa langsung ditempel dan hasilnya dilihat: https://tools.simonwillison.net/writing-style
  Riwayat percakapan Claude ada di sini: https://gist.github.com/simonw/e9902ed1cbda30f90db8d0d22caa0...

  • Sepertinya tidak bekerja dengan benar.
    Kira-kira pencocokan pola kedua terasa aneh.
    Misalnya, jika memasukkan “It is quite difficult to find untainted samples. We used various methods to isolate four samples.”, “quite” ditemukan di “is quite difficult to find untainted samples.”, sedangkan “various” ditemukan di string kosong.
    Meski begitu, saya suka alat HTML/JS cepat seperti ini.
  • Saya penasaran mengapa tidak meminta Claude meninjau tulisan secara langsung saja, alih-alih menyuruh Claude membuat skrip Bash yang lebih rapuh dan terbatas.
    Anda juga bisa meminta Claude menulis sendiri prompt yang melakukan fungsi yang sama atau lebih baik.
    Bash dan Perl adalah alat yang buruk untuk pekerjaan seperti ini, seperti lakban dan permen karet, sementara inilah jenis pekerjaan yang paling dikuasai Claude.
    Alih-alih sekadar menandai masalah, ia bisa menimbang alternatif dan menyarankan revisi, tanpa ketidakcocokan regex aneh yang menimbulkan false positive, false negative, dan kesalahan parsing.

• Pada Unix awal ada perintah diction dan style yang melakukan hal serupa.
  Bisa didapatkan dari GNU dan juga tersedia di Homebrew.
  https://www.gnu.org/software/diction/
  Seingat saya tidak terlalu hebat, dan kumpulan alat kali ini mungkin juga akan bekerja kurang lebih setara.

• Di bidang saya, kualitas tulisan berada di urutan paling bawah dalam hal pentingnya, bahkan lebih rendah daripada evaluasi kuliah
  Memang kalimat yang jelas dan ringkas dihargai, tetapi kalau Anda mahasiswa pascasarjana, rasanya akan lebih berguna melatih kemampuan presentasi, terutama saat menghadapi pertanyaan yang bermusuhan, dan sayangnya juga kemampuan menjilat
  Ya, saya punya pengalaman pahit :p

  • Mencari konselor mungkin lebih penting daripada kemampuan presentasi
    Orang-orang memang merasa kewalahan sampai tak sanggup menanggungnya, tetapi sebagian besar tekanan itu mereka ciptakan sendiri
    Taruhan sebenarnya tidak setinggi yang sudah dibesar-besarkan di kepala, dan orang-orang ingin Anda lulus
  • Saya tidak tahu bagaimana cara memastikan hal itu
    Tergantung bidangnya, tetapi fakta bahwa penelaah jarang menyebut kualitas tulisan bukan berarti itu tidak memengaruhi penerimaan
    Jika Anda membuat orang kesal, terutama dengan cara yang terasa tidak cukup substansial untuk ditulis dalam ulasan, mereka justru cenderung menjadi lebih kritis terhadap hal-hal yang biasanya akan mereka lewatkan
    Saya akui ini tidak memuaskan karena sulit dibantah, dan saya juga akui bahwa tulisan yang sengaja buruk kadang bisa dipakai untuk menutupi celah

• Pernyataan bahwa “untuk memasarkan sebuah makalah, penulis harus menyajikan alasan meyakinkan bahwa idenya layak mendapat akses ke sumber daya itu” berarti jurnal akademik pada akhirnya diisi bukan oleh ide paling penting, melainkan makalah yang paling berhasil dijual
  Seperti yang dikatakan penulis, unsur dangkal seperti salah ketik yang sulit ditemukan pun bisa menjadi faktor penentu karena penelaah dapat menemukannya
  Kita sebaiknya berhenti berpura-pura objektif dan menerima bahwa jurnal mencerminkan selera serta pandangan editor
  Atau, unggah saja semuanya ke tempat standar seperti arxiv
  Tidak ada sumber daya langka dalam mengunggah PDF

  • Yang sebenarnya membuat keputusan lebih dekat ke penelaah, bukan editor
    Jika penelaah memberi skor bagus atau skor yang aman, makalah akan diterbitkan begitu saja; jika mereka mengkritik keras makalahnya, editor akan menegakkan badan dan harus menilai apakah para penulis sudah cukup menanggapi keberatan penelaah
    Meski begitu, pihak yang menuntut standar tetaplah penelaah, bukan editor
  • Sekalian saja, saya berharap sistem sitasi juga diperbaiki agar daftar pustaka menjadi hyperlink, dan artefak kode juga bisa diakses

• Berguna bagi orang-orang yang, entah karena alasan apa, tidak memakai emacs
  Alur menjalankannya lalu mengedit lagi cukup merepotkan, sehingga mungkin sulit dijadikan alur kerja yang baik
  Penulis memberi kredit pada emacs “writegood”, tetapi plugin pemeriksa gaya bahasa favorit saya pribadi adalah “artbollocks-mode”

• Tulisan terkait:
  Shell scripts to improve your writing - https://news.ycombinator.com/item?id=13295530 - Januari 2017, 55 komentar
  Shell scripts to improve your writing, or "My advisor rewrote himself in bash." - https://news.ycombinator.com/item?id=1529166 - Juli 2010, 31 komentar