Hal-hal yang Saya Pikirkan Saat Mengedit (2019)
(evaparish.com)- Mengedit adalah pekerjaan memastikan apa yang sebenarnya ingin disampaikan oleh tulisan dan siapa pembacanya sebelum merapikan kalimat, dan prinsip dasar yang sama dapat diterapkan pada email, dokumen, blog, maupun novel
- Menegaskan kembali inti di awal dan akhir tulisan, serta menambahkan nomina alih-alih hanya memakai penunjuk seperti “this/that”, membantu pembaca tidak kehilangan konteks dan meningkatkan kejelasan
- Dengan mengurangi kata-kata yang tidak perlu, mengubah instruksi menjadi bentuk imperatif, serta memecah kalimat panjang dan struktur “of/for”, makna dapat tersampaikan lebih cepat
- Kalimat pasif, adverbia, jargon, dan klise dapat mengaburkan pelaku, makna yang tepat, dan cakupan pembaca, sehingga lebih baik diganti dengan verba dan penjelasan yang konkret
- Pengeditan yang baik bukan soal mengikuti aturan secara membabi buta, melainkan secara sadar memilih bahasa yang sesuai dengan pesan yang ingin disampaikan dan membuang ungkapan yang tidak perlu
Tentukan dulu apa yang sebenarnya ingin disampaikan tulisan
- Sebelum masuk ke pengeditan tingkat kalimat, kita perlu terlebih dahulu memastikan apakah tulisan benar-benar mengatakan apa yang dimaksudkan
- Menulis preamble pribadi untuk setiap tulisan memberi tolok ukur saat mengedit
- Pertanyaan intinya adalah “apa poin utamanya” dan “untuk siapa tulisan ini dibuat”
- Tulis informasi ini di bagian paling atas dokumen, lalu bandingkan dengan isi sebenarnya saat menulis dan mengedit
- Jika poin sebuah tulisan blog tidak bisa diringkas dalam satu atau dua kalimat, akan sulit menulisnya secara konsisten
- Dalam kelas menulis kreatif di Writers Studio, setiap tugas diawali dengan preamble yang mencakup narator yang dimaksud, tone, dan suasana, dan penilaian berfokus pada teknik serta apakah niat penulis tercapai, bukan pada selera
Pengulangan adalah alat untuk menjaga pembaca tetap mengikuti
- Meski inti tulisan terasa sudah cukup jelas, mengatakannya lagi di awal dan akhir membantu pembaca mengikuti poin utama dengan lebih baik
- Tutorial dokumentasi biasanya lebih baik jika disusun dengan pola memperkenalkan apa yang akan dilakukan, memberikan prosedur, lalu memverifikasi apakah langkahnya dilakukan dengan benar
- Tulisan blog juga cocok memakai pola memperkenalkan topik, mengembangkannya di isi, lalu menutup dengan ringkasan singkat
- Pengulangan juga dibutuhkan pada tingkat bahasa
- Jangan hanya memakai kata ganti penunjuk seperti “this” atau “that”; tambahkan nomina yang menjelaskan apa yang dirujuk
- “To solve this” lebih jelas jika menjadi “To solve this shortage”
- “That will take you to the home screen” lebih jelas jika menjadi “Successfully authenticating will take you to the home screen”
- Meski bagi penulis terasa seperti pengulangan, bagi pembaca itu adalah bentuk klarifikasi yang memudahkan mereka mengikuti tulisan
Penyederhanaan: buang kata-kata yang tidak bermakna
- Pekerjaan terpenting dalam mengedit adalah menghapus kata-kata yang tidak menambah makna
- “You will need to run this script” dapat dipersingkat menjadi “Run this script”
- “You can aid in readability by making sure…” dapat dipersingkat menjadi “Make sure…”
- Kecuali ada alasan khusus, sebaiknya segera sampai ke pokok bahasan dan tidak mengubur makna di bawah terlalu banyak kata atau struktur kalimat yang dekoratif
-
Ubah instruksi menjadi bentuk imperatif
- Dalam instruksi, “You should X” atau “You can X” lebih ringkas jika diubah ke bentuk imperatif
- “You should save the file to your home directory” menjadi “Save the file to your home directory”
- Perubahan ini mengurangi jumlah kata dan langsung mendorong pembaca untuk bertindak
-
Kurangi struktur “of” dan “for”
- Struktur berantai dengan “of” atau “for” lebih efisien jika ditulis ulang dengan menempatkan informasi sebelum nomina utama
- “The manager of the team responsible for marketing” menjadi “The marketing team’s manager”
- Kalimat yang disusun ulang membuat pembaca lebih cepat menangkap makna tanpa harus terus merevisi pemahaman mereka di setiap frasa
-
Pecah kalimat panjang dan gunakan koma
- Kalimat panjang sebaiknya dipecah menjadi beberapa kalimat yang lebih pendek
- Contoh proyek Acme memuat milestone, lingkungan server, peningkatan waktu build, dan perbandingan dengan XYZ plan dalam satu kalimat, lalu versi revisinya memecah semua itu menjadi tiga kalimat
- Versi revisi menyampaikan secara terpisah bahwa server non-staging berjalan di lingkungan Foobaz, build turun menjadi kurang dari 10 menit, dan pada XYZ plan sebelumnya butuh lebih dari 1 jam
- Menambahkan koma di posisi yang tepat membantu pembaca memproses bagian awal sebelum membaca sisanya
- “If you’re looking for me, I’ll be in my office”
- “Due to the fog, our flight was delayed”
- Saat anak kalimat dependen berada di awal kalimat, koma diperlukan, dan koma itu menjadi titik pemrosesan yang membantu pembacaan
Kurangi ungkapan yang mengaburkan pelaku dan makna
-
Hilangkan kalimat pasif
- Kalimat pasif menyembunyikan siapa atau apa yang melakukan tindakan
- Jika kalimat pasif diubah menjadi aktif, pembaca dapat menghubungkan tindakan dengan orang atau objek yang tepat sehingga kalimat menjadi lebih jelas
- “The fire alarm was pulled and the building was evacuated” mengungkapkan pelaku dengan lebih baik jika ditulis “The fire marshal pulled the alarm and the employees evacuated the building”
- “Millions of dollars were embezzled from the company” menjadi lebih jelas jika ditulis “Two executives embezzled millions of dollars from the company”
- Dalam penjelasan sistem, menulis “An alert is triggered and the job is started” tidak menjelaskan layanan mana yang memicu alert atau komponen mana yang menjalankan job
- Dalam dokumentasi teknis, tidak menyebutkan pelaku tindakan menurunkan presisi
-
Gunakan verba dan deskripsi konkret alih-alih adverbia
- Adverbia hampir selalu bisa diganti dengan verba atau penjelasan yang lebih konkret
- “He laughed loudly” membuat pembaca menebak seberapa keras atau seperti apa tawa itu
- Jika maksud sebenarnya adalah “dia tertawa begitu keras sampai seluruh restoran menoleh”, lebih baik menggambarkan situasinya secara langsung
- Adverbia seperti “Basically” dan “Essentially” sering dipakai sebagai hedge, jadi lebih baik dihapus dan menyatakan maksud secara langsung
Jangan mengasumsikan pengetahuan dan tone pembaca
-
Jelaskan singkatan dan konsep
- Saat menulis tentang topik yang sangat dikuasai, kita mudah lupa bahwa pembaca mungkin tidak punya latar belakang yang sama
- Singkatan dan inisialisme sebaiknya ditulis lengkap saat pertama muncul, lalu singkatannya diletakkan dalam tanda kurung dan setelah itu cukup gunakan singkatannya
- “TTFB” pertama kali ditulis sebagai “time to first byte (TTFB)”
- Menambahkan penjelasan singkat saat sebuah konsep pertama kali muncul memudahkan pembaca mengikuti
- TTFB mengukur waktu dari saat pengguna mengirim permintaan HTTP hingga browser memuat byte pertama
- Ini digunakan sebagai metrik responsivitas situs web
- Jika perlu, dapat diberikan tautan pembelajaran tambahan seperti time to first byte (TTFB) metric
-
Konsistensi tone
- Tone tulisan, baik percakapan maupun formal, sebaiknya dipilih satu lalu dijaga tetap konsisten
- Jika satu kalimat dimulai dengan sangat percakapan lalu tiba-tiba berubah menjadi sangat akademis, pembaca bisa bingung atau teralihkan dari isi yang ingin disampaikan
- Kalimat contoh dapat diubah ke tone yang konsisten, misalnya “awalnya saya antusias dengan framework baru itu, tetapi saya tidak berhasil mendapatkan metrik yang saya inginkan”
Rapikan jargon, klise, dan struktur visual
-
Hindari jargon dan klise
- Jargon bisnis mencakup ungkapan seperti “deep dive” dan “low-hanging fruit”, sementara tulisan lain sering memakai klise seperti metafora baseball
- Jargon mengasumsikan bahwa pembaca termasuk dalam kelompok internal yang memakai ungkapan tersebut
- Bagi pembaca non-penutur asli bahasa Inggris atau yang tidak akrab dengan budaya baseball, jargon dan klise dapat membuat tulisan lebih sulit diikuti
- “tl;dr, if you can hack something together by EOD…” mengandung singkatan dan slang teknis, serta tidak terdengar seperti permintaan
- “Can you deliver a prototype by the end of today?” menjadi permintaan yang jelas karena langsung menanyakan hasil yang dibutuhkan dan tenggatnya
-
Gunakan ruang kosong dan format
- Ruang kosong penting dalam dokumentasi teknis, dan juga efektif dalam tulisan blog maupun email
- Paragraf panjang sulit dibaca, terutama di layar komputer, dan bisa membuat pembaca kehilangan fokus
- Membagi halaman secara visual memudahkan pembaca menemukan inti
- Paragraf panjang sebaiknya dipecah menjadi beberapa paragraf pendek
- Bangun struktur dengan subjudul yang berguna agar pembaca bisa melompat ke bagian yang mereka minati
- Susun item yang saling terkait dalam bentuk daftar
- Saat menyampaikan banyak informasi seperti dalam dokumen referensi, tabel bisa lebih baik daripada daftar
- Gunakan huruf tebal agar pembaca yang memindai cepat tetap bisa menangkap poin penting
Filsafat pengeditan
- Filsafat pengeditan dapat diringkas menjadi dua hal
- Jangan bergantung pada adverbia, jargon, klise, atau hedge; katakan dengan tepat apa yang dimaksud
- Hapus semua kata yang tidak perlu
- Dua prinsip ini menjadi kerangka untuk memperbaiki tulisan sendiri dan menilai tulisan orang lain
- Dengan latihan, kita akan membentuk gaya dan preferensi sendiri, dan tidak apa-apa menyimpang dari sebagian anjuran jika tahu alasannya
- Tujuan pengeditan bukan mengikuti aturan tanpa berpikir kritis, melainkan menggunakan bahasa secara sadar dan membuat pilihan yang sesuai dengan pesan yang ingin disampaikan
1 komentar
Komentar Hacker News
Saya penulis artikel ini. Saya senang dan merasa terhormat karena tulisan ini ternyata beresonansi dengan banyak orang. Setelah menulisnya, saya mengikuti rasa ingin tahu saya dan benar-benar menjadi software engineer; setelah bekerja beberapa tahun, saya mulai merindukan peran yang porsi menulisnya besar. Jika Anda sedang mencari technical writer yang hebat, developer advocate, atau peran yang memadukan keahlian komunikasi dan kemampuan teknis, beri tahu saya. Anda bisa menghubungi saya lewat formulir situs web(https://evaparish.com/contact) atau LinkedIn.
Salah satu hal yang paling mengganggu saat membaca dokumentasi teknis adalah ketika muncul singkatan yang belum pernah diperkenalkan kepada pembaca. Hal seperti ini berulang di berbagai bagian dokumentasi proyek, dan ketika penanggung jawab berganti dalam beberapa tahun, bisa sampai tidak ada lagi yang tahu singkatan tertentu itu kependekan dari apa. Saya benar-benar beberapa kali melihat situasi aneh ketika sebuah tim mengembangkan dan memelihara layanan bernama ABC, tetapi tak seorang pun anggota tim tahu ABC itu singkatan dari apa. Dalam kasus seperti itu, untuk menghindari pekerjaan memilih nama baru dan memperbarui semua dokumen terkait, mereka akhirnya memperlakukan ABC seperti nama diri saja dan lanjut. Contoh fiktif: Untuk mendapatkan access token untuk CDIS, buka DMC milik lalu klik item "CDIS" di sidebar kiri, lalu tekan "Generate Access Token" untuk menyalin token. Saya lebih ingin membacanya seperti ini: Untuk mendapatkan access token untuk Customer Data Indexing Service(CDIS), buka Data Management Console(DMC) milik lalu klik item "CDIS" di sidebar kiri, lalu tekan "Generate Access Token" untuk menyalin token.