Penulisan Teknis untuk Pengembang

HTML, CSS, JavaScript, Python, PHP, C++, Dart — ada begitu banyak bahasa pemrograman di luar sana dan Anda bahkan mungkin benar-benar fasih dalam beberapa di antaranya! Tetapi karena kami bertujuan untuk menulis kode yang lebih banyak dan lebih baik, cara kami menulis dan berkomunikasi dalam bahasa sehari-hari menjadi semakin penting… dan bahkan mungkin diabaikan.

Cara kita menulis tentang dan seputar kode bisa dibilang sama pentingnya dengan kode itu sendiri. Dan terlepas dari di mana Anda jatuh pada garis itu, kita semua dapat setuju bahwa kata-kata kita berpotensi membantu dan merusak efektivitas kode.

Dalam artikel ini, saya ingin menguraikan bagaimana dua bidang yang tampaknya berbeda ini — pemrograman dan penulisan — dapat bersatu dan membawa keterampilan pengembang kami ke tingkat berikutnya.

Tunggu, penulisan teknis? Ya, itulah yang saya maksud. Saya benar-benar percaya kita semua adalah penulis dalam satu atau lain hal. Dan saya di sini untuk memberi Anda panduan dengan tips menulis, saran, dan contoh bagaimana hal itu dapat membuat Anda menjadi pengembang dan komunikator yang lebih baik.

Penulisan teknis ada di mana-mana

Tahun lalu, tim di balik klien Mac Git yang populer, Tower, mensurvei lebih dari 4,000 pengembang dan menemukan bahwa hampir 50% dari mereka menghabiskan antara 3-6 jam sehari untuk menulis kode.

Dan ya, itu salah satu survei polling kelompok niche yang cantik, tapi saya membayangkan banyak dari kita jatuh di suatu tempat dalam kisaran itu. Apa pun masalahnya, pengembang tidak menulis kode 24/7, karena seperti yang disarankan oleh jajak pendapat ini, kami menghabiskan banyak waktu untuk melakukan hal lain.

Itu mungkin termasuk:

• mendemonstrasikan fitur baru,
• mendokumentasikan fitur baru itu,
• memperbarui tiket kerja yang terkait dengan fitur baru itu, atau
• backlogging berfungsi untuk mendukung fitur baru itu.

Tentu saja, selalu ada waktu untuk istirahat di kamar mandi dan Wordle juga.

Bagaimanapun, sebagian besar hal yang biasanya kami lakukan melibatkan komunikasi dengan orang-orang seperti tim Anda, kolega, klien, pengguna, dan pengembang lainnya.

Jadi kami menghabiskan sebagian besar waktu kami untuk berkomunikasi dengan manusia melalui kata selain komunikasi yang kita miliki dengan komputer melalui kode. Kata-kata adalah bahasa tertulis. Dan jika kita menulis kata-kata kita dengan lebih baik, kita akan berkomunikasi dengan lebih baik. Ketika kita berkomunikasi dengan lebih baik, kita cenderung mendapatkan apa yang kita inginkan.

Itu Penulisan Teknis 101.

Dan itu tidak berakhir di sini.. Beberapa programmer juga suka membuat produk mereka sendiri, yang berarti mereka harus menjadikan pemasaran sebagai bagian dari pekerjaan mereka. Penulisan teknis memainkan peran besar dalam hal itu juga. Jadi, ya. Saya pikir cukup adil untuk mengatakan bahwa penulisan teknis adalah memang dimana mana.

Apa itu tata bahasa yang baik?

Dengan begitu banyak bahasa pemrograman di luar sana, hal terakhir yang kami inginkan adalah mempelajari satu lagi.

Tatabahasa merupakan bagian integral dari bahasa Inggris, dan membuka potensi penuh komunikasi. Itu membuat kita lebih formal, profesional, dan koheren.

Biarkan saya memberi Anda ikhtisar singkat tentang bahasa.

Sintaks bahasa Inggris

Sama seperti bahasa pemrograman, bahasa Inggris memiliki sintaks yang terdefinisi dengan baik, dan dimulai dengan kata-kata.

Kata-kata adalah blok bangunan bahasa Inggris, dan mereka termasuk dalam delapan ember:

Pikirkan ini seperti UI komponen: mereka adalah bagian modular yang dapat Anda pindahkan untuk menyusun kalimat yang lengkap dan kuat, dengan cara yang sama Anda dapat menyusun kalimat yang lengkap dan kuat UI. Apakah semua komponen harus selalu ada? Tentu tidak! Rakit kalimat dengan potongan-potongan yang Anda butuhkan untuk menyelesaikan pengalaman, seperti yang Anda lakukan dengan antarmuka.

Suara dan nada

Kosa kata, tanda baca, struktur kalimat, dan pilihan kata. Ini semua adalah bahan-bahan bahasa Inggris. Kami menggunakannya untuk berbagi ide, berkomunikasi dengan teman dan keluarga kami, dan mengirim email ke rekan kerja kami.

Tetapi sangat penting untuk mempertimbangkan suara dari pesan kami. Sungguh menakjubkan bagaimana satu tanda seru dapat sepenuhnya mengubah nada pesan:

1. Saya suka pemrograman.
2. I 'like' pemrograman! :)

Sangat mudah untuk membingungkan suara dengan nada, dan sebaliknya.

Suara adalah apa yang menyangkut pilihan kata-kata kita, yang tergantung pada konteksnya. Misalnya, tutorial untuk pemula lebih cenderung menggunakan bahasa gaul dan informal untuk menyampaikan suara yang ramah, sedangkan dokumentasi mungkin ditulis secara formal, serius, dan profesional dalam upaya untuk langsung ke intinya.

Pesan yang sama, ditulis dengan dua suara berbeda:

• Fun: “Perluas jejaring sosial Anda dan tetap perbarui apa yang sedang tren sekarang.”
• Serius: "Temukan pekerjaan di salah satu aplikasi jejaring sosial terbesar dan pasar pekerjaan online."

Bukan hal yang aneh untuk secara tidak sengaja menulis pesan yang terkesan merendahkan, menyinggung, dan tidak profesional. Di sinilah nada ikut bermain. Baca pesan Anda dengan keras, buat orang lain membacanya untuk Anda, dan bereksperimenlah dengan tanda baca dan struktur kalimat Anda. Begitulah cara Anda mengasah nada Anda.

Inilah cara lain untuk memikirkannya: suara Anda tidak pernah berubah, tetapi nada Anda berubah. Suara Anda mirip dengan siapa Anda sebagai pribadi, sedangkan nada adalah bagaimana Anda merespons dalam situasi tertentu.

Suara aktif dan pasif

Sebuah kalimat selalu mengandung aktor, kata kerja, dan target. Urutan kemunculannya menentukan apakah kalimat tersebut ditulis dengan kalimat aktif atau pasif.

Aktor datang pertama dalam suara aktif. Misalnya: "CSS melukis latar belakang."

Kalimat yang menggunakan suara aktif lebih lugas daripada kalimatnya. Mereka lebih jelas, lebih pendek, dan lebih mudah dimengerti — sempurna untuk suara yang lebih profesional yang langsung ke intinya.

Dengan suara pasif, aktor datang terakhir. (Lihat apa yang saya lakukan di sana?) Itu berarti aktor kita — dalam hal ini CSS — muncul di akhir seperti ini: “Latar belakang dilukis oleh CSS.”

Pembaca biasanya mengubah suara pasif menjadi suara aktif di kepala mereka, menghasilkan lebih banyak waktu pemrosesan. Jika Anda pernah mendengar bahwa menulis dengan suara aktif lebih baik, biasanya inilah alasannya. Penulis teknologi lebih memilih suara aktif hampir sepanjang waktu, dengan sedikit pengecualian seperti mengutip penelitian: "Telah disarankan bahwa ..."

Tapi itu tidak berarti Anda harus selalu berusaha untuk suara yang aktif. Beralih dari satu kalimat ke kalimat lainnya — bahkan dalam paragraf yang sama — dapat membuat konten Anda mengalir lebih lancar dari satu kalimat ke kalimat lainnya jika digunakan secara efektif.

Menghindari kesalahan

Tata bahasa adalah semua tentang struktur dan kebenaran bahasa, dan tidak ada yang lebih baik untuk mencapai itu daripada mengoreksi dokumen Anda dengan cepat. Sangat penting untuk membersihkan tulisan Anda dari kesalahan ejaan, masalah tata bahasa, dan ketidaksempurnaan semantik.

Di akhir artikel ini, saya akan menunjukkan alat berharga yang digunakan para profesional untuk menghindari kesalahan penulisan. Jelas, ada pemeriksa ejaan bawaan di hampir semua hal akhir-akhir ini; editor kode kami bahkan memiliki plugin pemeriksa ejaan dan linting untuk membantu mencegah kesalahan. 

Tetapi jika Anda mencari alat satu atap untuk semua hal tata bahasa, Grammarly merupakan salah satu alat yang paling banyak digunakan. Saya tidak mendapatkan suap untuk itu atau apa pun. Ini hanya alat yang sangat hebat yang digunakan banyak editor dan penulis untuk menulis konten yang bersih dan jelas — mirip dengan cara Anda menggunakan Emmet, eslint, atau linter lainnya untuk menulis kode yang bersih dan jelas.

Menulis komentar kode

Hal-hal yang kami tulis untuk pengembang lain dapat berdampak besar pada kualitas keseluruhan pekerjaan kami, apakah itu yang kami tulis dalam kode, bagaimana kami menjelaskan kode, atau bagaimana kami memberikan umpan balik pada sepotong kode.

Sangat menarik bahwa setiap bahasa pemrograman dilengkapi dengan serangkaian fitur standar untuk menulis komentar. Mereka harus menjelaskan apa yang dilakukan kode tersebut. Maksud saya bukan komentar samar seperti ini:

red *= 1.2 // Multiply `red` by 1.2 and re-assign it

Sebagai gantinya, gunakan komentar yang memberikan lebih banyak informasi:

red *= 1.2 // Apply a 'reddish' effect to the image

Ini semua tentang konteks. “Program seperti apa yang saya buat?” adalah jenis pertanyaan yang harus Anda tanyakan pada diri sendiri.

Komentar harus menambah nilai

Sebelum kita melihat apa yang membuat komentar kode “baik”, berikut adalah dua contoh komentar malas:

const age = 32 // Initialize `age` to 32

filter: blur(32px); /* Create a blur effect with a 32px radius */

Ingatlah bahwa tujuan dari sebuah komentar adalah untuk menambah nilai pada sepotong kode, bukan untuk mengulanginya. Jika Anda tidak dapat melakukannya, lebih baik Anda membiarkan kode apa adanya. Apa yang membuat contoh-contoh ini "malas" adalah bahwa mereka hanya menyatakan kembali apa yang jelas dilakukan oleh kode. Dalam hal ini, komentarnya berlebihan karena memberi tahu kita apa yang sudah kita ketahui — komentar itu tidak menambah nilai!

Komentar harus mencerminkan kode saat ini

Komentar kedaluwarsa bukanlah pemandangan yang langka di proyek-proyek besar; berani saya katakan dalam paling proyek.

Mari kita bayangkan David, seorang programmer dan pria yang keren untuk diajak bergaul. David ingin mengurutkan daftar string menurut abjad dari A ke Z, jadi dia melakukan yang jelas dalam JavaScript:

cities = sortWords(cities) // sort cities from A to Z

David kemudian menyadari bahwa sortWords() sebenarnya mengurutkan daftar dari Z ke A. Itu bukan masalah, karena dia bisa membalikkan hasilnya:

cities = sortWords(cities) // sort cities from A to Z
cities = reverse(cities)

Sayangnya, David tidak memperbarui komentar kodenya.

Sekarang bayangkan saya tidak menceritakan kisah ini kepada Anda, dan yang Anda lihat hanyalah kode di atas. Anda tentu akan berpikir bahwa setelah menjalankan baris kode kedua, `kota` akan diurutkan dari Z ke A! Kegagalan seluruh kebingungan ini disebabkan oleh komentar basi.

Meskipun ini mungkin contoh yang dilebih-lebihkan, hal serupa dapat (dan sering terjadi) terjadi jika Anda berpacu dengan tenggat waktu yang dekat. Untungnya, ini dapat dicegah dengan mengikuti satu aturan sederhana… ubah komentar Anda saat Anda mengubah kode.

Itulah satu aturan sederhana yang akan menyelamatkan Anda dan tim Anda dari banyak hal hutang teknis.

Sekarang kita tahu seperti apa komentar yang ditulis dengan buruk, mari kita lihat beberapa contoh yang bagus.

Komentar harus menjelaskan kode unidiomatik

Terkadang, itu alam cara melakukan sesuatu tidak benar. Pemrogram mungkin harus "melanggar" standar sedikit, tetapi ketika mereka melakukannya, disarankan untuk meninggalkan sedikit komentar yang menjelaskan alasan mereka:

 function addSetEntry(set, value) {    
  /* Don't return `set.add` because it's not chainable in IE 11. */  
  set.add(value);
  return set;
}

Itu membantu, bukan? Jika Anda bertanggung jawab untuk meninjau kode ini, Anda mungkin tergoda untuk memperbaikinya tanpa komentar yang menjelaskan apa yang terjadi.

Komentar dapat mengidentifikasi tugas di masa mendatang

Hal lain yang berguna untuk dilakukan dengan komentar adalah mengakui bahwa masih banyak pekerjaan yang harus dilakukan.

// TODO: use a more efficient algorithm
linearSort(ids)

Dengan cara ini, Anda dapat tetap fokus pada aliran Anda. Dan di kemudian hari, Anda (atau orang lain) dapat kembali dan memperbaikinya.

Komentar dapat menautkan kembali ke sumbernya

Jadi, Anda baru saja menemukan solusi untuk masalah Anda di StackOverflow. Setelah menyalin-menempelkan kode itu, terkadang ada baiknya menyimpan tautan ke jawaban yang membantu Anda sehingga Anda dapat kembali ke sana untuk referensi di masa mendatang.

// Adds handling for legacy browsers
// https://stackoverflow.com/a/XXXXXXX

Ini penting karena solusi bisa berubah. Itu selalu baik untuk mengetahui dari mana kode Anda berasal jika pernah rusak.

Menulis permintaan tarik

Tarik permintaan (PRs) merupakan aspek fundamental dari setiap proyek. Mereka duduk di jantung ulasan kode. Dan tinjauan kode dapat dengan cepat menjadi hambatan dalam kinerja tim Anda tanpa kata-kata yang baik.

Baik PR deskripsi merangkum apa perubahan sedang dilakukan dan mengapa itu sedang dibuat. Proyek besar memiliki templat permintaan tarik, seperti yang ini diadaptasi dari a contoh nyata:

## Proposed changes
Describe the big picture of your changes here to communicate to the maintainers why we should accept this pull request.

## Types of changes
What types of changes does your code introduce to Appium?
 - [ ] Bugfix (non-breaking change which fixes an issue)
 - [ ] New feature (non-breaking change which adds functionality)
 - ...

## Checklist
 - [ ] I have read the CONTRIBUTING doc
 - [ ] I have signed the CLA
 - [ ] Lint and unit tests pass locally with my changes

## Further comments
If this is a relatively large or complex change, kick off the discussion by explaining why you chose the solution you did and what alternatives you considered, etc…

Hindari kabur PR judul

Harap hindari judul yang terlihat seperti ini:

• Perbaiki bangunan.
• Perbaiki bug.
• Tambahkan tambalan.

Ini bahkan tidak usaha untuk menjelaskan build, bug, atau patch apa yang sedang kita hadapi. Sedikit detail tambahan tentang bagian build mana yang diperbaiki, bug mana yang terjepit, atau tambalan apa yang ditambahkan dapat membantu membangun komunikasi dan kolaborasi yang lebih baik dengan rekan kerja Anda. Ini mengatur level dan membuat orang-orang pada halaman yang sama.

PR judul secara tradisional ditulis dalam waktu imperatif. Itu adalah ringkasan satu baris dari keseluruhan PR, dan mereka harus menjelaskan apa sedang dilakukan oleh PR.

Berikut adalah beberapa contoh yang baik:

• Mendukung atribut srcset khusus di NgOptimizedImage
• Konfigurasi gambar default ke kualitas gambar 75%
• Tambahkan pemilih eksplisit untuk semua ControlValueAccessors bawaan

Hindari panjang PRs

Sebuah besar PR berarti deskripsi besar, dan tidak ada yang ingin meninjau ratusan atau ribuan baris kode, terkadang hanya untuk mengakhiri semuanya!

Sebagai gantinya, Anda dapat:

• berkomunikasi dengan tim Anda melalui Isu,
• membuat rencana,
• memecah masalah menjadi bagian-bagian yang lebih kecil, atau
• kerjakan setiap bagian secara terpisah dengan miliknya sendiri PR.

Bukankah sekarang jauh lebih bersih?

Berikan detail di PR tubuh

Berbeda dengan PR judul, tubuh adalah itu tempat untuk semua detail, termasuk:

• Mengapa PR sedang dilakukan?
• Mengapa ini pendekatan terbaik?
• Setiap kekurangan pendekatan, dan ide untuk menyelesaikannya jika memungkinkan
• Bug atau nomor tiket, hasil benchmark, dll.

Melaporkan bug

Laporan bug adalah salah satu aspek terpenting dari proyek apa pun. Dan semua proyek hebat dibangun berdasarkan umpan balik pengguna. Biasanya, bahkan setelah pengujian yang tak terhitung jumlahnya, penggunalah yang menemukan sebagian besar bug. Pengguna juga idealis yang hebat, dan terkadang mereka memiliki ide fitur; tolong dengarkan mereka!

Untuk proyek teknis, semua hal ini dilakukan dengan melaporkan masalah. Masalah yang ditulis dengan baik mudah ditemukan dan ditanggapi oleh pengembang lain.

Misalnya, sebagian besar proyek besar datang dengan sebuah templat:

 <!-- Modified from angular-translate/angular-translate -->
 ### Subject of the issue
 Describe your issue here.

 ### Your environment
 * version of angular-translate
 * version of angular
 * which browser and its version

 ### Steps to reproduce
 Tell us how to reproduce this issue.

 ### Expected behavior
 Tell us what should happen.

 ### Actual behavior
 Tell us what happens instead.

Kumpulkan tangkapan layar

Tangkap masalah menggunakan . Anda utilitas pemotretan layar sistem.

Jika itu adalah tangkapan layar dari CLI program, pastikan teksnya jelas. Jika itu adalah UI program, pastikan tangkapan layar menangkap elemen dan status yang tepat.

Anda mungkin perlu menangkap interaksi yang sebenarnya untuk menunjukkan masalah tersebut. Jika itu masalahnya, cobalah untuk rekam GIF menggunakan alat perekaman layar.

Bagaimana mereproduksi masalah

Jauh lebih mudah bagi pemrogram untuk memecahkan bug saat bug tersebut aktif di komputer mereka. Itu sebabnya komit yang baik harus disertai dengan langkah-langkah untuk mereproduksi masalah dengan tepat.

Berikut ini adalah contohnya:

Update: you can actually reproduce this error with objects:

 ```html
 <div *ngFor="let value of objs; let i = index">
   <input [ngModel]="objs[i].v" (ngModelChange)="setObj(i, $event)" />
 </div>
 ```

 ```js
 export class OneComponent {
   obj = {v: '0'};
   objs = [this.obj, this.obj, this.obj, this.obj];
 ​
  setObj(i: number, value: string) {
     this.objs[i] = {v: value};
  }
 }
 ```

 The bug is reproducible as long as the trackBy function returns the same value for any two entries in the array. So weird behavior can occur with any duplicate values.

Sarankan penyebabnya

Andalah yang menangkap bug, jadi mungkin Anda dapat menyarankan beberapa penyebab potensial mengapa bug itu ada. Mungkin bug itu hanya terjadi setelah Anda menemui event tertentu, atau mungkin hanya terjadi di ponsel.

Juga tidak ada salahnya untuk menjelajahi basis kode, dan mungkin mengidentifikasi apa yang menyebabkan masalah. Kemudian, Masalah Anda akan ditutup lebih cepat dan kemungkinan Anda akan ditugaskan ke yang terkait PR.

Berkomunikasi dengan klien

Anda dapat bekerja sebagai pekerja lepas solo, atau mungkin Anda adalah pengembang utama di tim kecil. Dalam kedua kasus tersebut, katakanlah Anda bertanggung jawab untuk berinteraksi dengan klien pada sebuah proyek. 

Sekarang, stereotip programmer adalah bahwa kita adalah komunikator yang buruk. Kami dikenal menggunakan jargon yang terlalu teknis, memberi tahu orang lain apa yang mungkin dan tidak mungkin, dan bahkan bersikap defensif ketika seseorang mempertanyakan pendekatan kami.

Jadi, bagaimana kita mengurangi stereotip itu? Tanyakan kepada klien apa yang mereka inginkan, dan selalu dengarkan umpan balik mereka. Berikut cara melakukannya.

Ajukan pertanyaan yang tepat

Mulailah dengan memastikan bahwa Anda dan klien berada di halaman yang sama:

• Siapa audiens target Anda?
• Apa tujuan dari situs tersebut?
• Siapa pesaing terdekat Anda dan apa yang mereka lakukan dengan benar?

Mengajukan pertanyaan juga merupakan cara yang baik untuk menulis secara positif, terutama dalam situasi ketika Anda tidak setuju dengan umpan balik atau keputusan klien. Mengajukan pertanyaan memaksa orang tersebut untuk mendukung klaim mereka sendiri daripada Anda menyerang mereka dengan mempertahankan posisi Anda sendiri:

• Apakah Anda setuju dengan itu bahkan jika itu datang dengan biaya kinerja tambahan?
• Apakah memindahkan komponen membantu kita mencapai tujuan kita dengan lebih baik?
• Hebat, siapa yang bertanggung jawab untuk mempertahankannya setelah peluncuran? 
• Tahukah Anda begitu saja jika kontras antara kedua warna tersebut melewati standar WCAG AA?

Pertanyaan jauh lebih polos dan meningkatkan rasa ingin tahu atas permusuhan.

Jual diri Anda

Jika Anda melakukan promosi ke calon klien, Anda harus meyakinkan mereka untuk mempekerjakan Anda. Mengapa klien harus memilih Anda? Penting untuk menentukan hal berikut:

• Siapa kamu
• Apa yang kamu lakukan
• Mengapa Anda cocok untuk pekerjaan itu?
• Tautan ke pekerjaan relevan yang telah Anda lakukan

Dan begitu Anda mendapatkan pekerjaan dan perlu menulis kontrak, ingatlah bahwa tidak ada konten yang lebih mengintimidasi daripada sekumpulan legalese. Meskipun ditulis untuk proyek desain, Pembunuh Kontrak bisa menjadi titik awal yang bagus untuk menulis sesuatu yang jauh lebih ramah.

Perhatian Anda terhadap detail bisa menjadi perbedaan antara Anda dan pengembang lain yang mencoba memenangkan proyek yang sama. Dalam pengalaman saya, klien akan dengan mudah menyewa pengembang yang mereka pikir akan mereka nikmati bekerja dengan daripada orang yang secara teknis paling kompeten atau berpengalaman untuk pekerjaan itu.

Menulis mikrokopi

Mikrofotokopi adalah seni menulis yang mudah digunakan UI pesan, seperti kesalahan. Saya berani bertaruh ada saat-saat di mana Anda sebagai pengembang harus menulis pesan kesalahan karena pesan itu diletakkan di backburner sampai waktu peluncuran.

Mungkin itu sebabnya kami terkadang melihat kesalahan seperti ini:

Error: Unexpected input (Code 693)

Kesalahan adalah hal terakhir yang Anda ingin pengguna Anda tangani. Tapi itu memang terjadi, dan tidak ada yang bisa kita lakukan untuk itu. Berikut adalah beberapa tip untuk meningkatkan keterampilan mikrokopi Anda.

Hindari jargon teknis

Kebanyakan orang tidak tahu apa itu server, sementara 100% programmer tahu. Itu sebabnya tidak jarang melihat istilah yang tidak biasa ditulis dalam pesan kesalahan, seperti API atau "eksekusi batas waktu".

Kecuali jika Anda berurusan dengan klien teknis atau basis pengguna, kemungkinan besar sebagian besar pengguna Anda tidak mengambil kursus ilmu komputer, dan tidak tahu cara kerja Internet, dan mengapa hal tertentu tidak berhasil. Oleh karena itu, kesalahan.

Oleh karena itu, pesan kesalahan yang baik seharusnya tidak menjelaskan mengapa ada yang tidak beres, karena penjelasan seperti itu mungkin memerlukan penggunaan istilah teknis yang menakutkan. Itulah mengapa sangat penting untuk menghindari penggunaan jargon teknis.

Jangan pernah menyalahkan pengguna

Bayangkan ini: Saya mencoba masuk ke platform Anda. Jadi saya membuka browser saya, mengunjungi situs web Anda, dan memasukkan detail saya. Kemudian saya diberi tahu: “Email/kata sandi Anda salah.”

Meskipun tampaknya dramatis untuk berpikir bahwa pesan ini bermusuhan, secara tidak sadar membuat saya merasa bodoh. Microcopy mengatakan bahwa tidak boleh menyalahkan pengguna. Coba ubah pesan Anda menjadi sesuatu yang tidak terlalu mencolok, seperti ini contoh yang diadaptasi dari login Mailchimp: “Maaf, kombinasi email-sandi itu salah. Kami dapat membantu Anda memulihkan akun Anda.”

Saya juga ingin menambahkan pentingnya menghindari SEMUA CAPS dan tanda seru! Tentu, mereka dapat digunakan untuk menyampaikan kegembiraan, tetapi dalam mikrokopi mereka menciptakan rasa permusuhan terhadap pengguna.

Jangan membanjiri pengguna

Menggunakan humor dalam salinan Anda adalah ide yang bagus! Ini dapat meringankan suasana hati, dan ini adalah cara mudah untuk mengekang hal negatif yang disebabkan bahkan oleh kesalahan terburuk sekalipun.

Tetapi jika Anda tidak menggunakannya benar-benar, itu bisa dianggap merendahkan dan menghina pengguna. Itu hanya besar risiko untuk diambil.

Mailchimp mengatakannya dengan baik:

[J]jangan keluar dari cara Anda untuk membuat lelucon — humor yang dipaksakan bisa lebih buruk daripada tidak sama sekali. Jika Anda tidak yakin, tetaplah berwajah datar.

(Tekankan milikku)

Menulis markup yang dapat diakses

Kami dapat dengan mudah menghabiskan seluruh artikel tentang aksesibilitas dan bagaimana kaitannya dengan penulisan teknis. Heck, aksesibilitas sering disertakan dalam panduan gaya konten, termasuk untuk Microsoft dan MailChimp.

Anda seorang pengembang dan mungkin sudah tahu banyak tentang aksesibilitas. Anda bahkan mungkin salah satu pengembang yang lebih rajin yang menjadikan aksesibilitas sebagai bagian inti dari alur kerja Anda. Namun, sungguh menakjubkan seberapa sering pertimbangan aksesibilitas diletakkan di belakang burner, tidak peduli betapa pentingnya kita semua tahu untuk membuat pengalaman online yang dapat diakses yang mencakup semua kemampuan.

Jadi, jika Anda menemukan diri Anda menerapkan copywriting orang lain ke dalam kode Anda, menulis dokumentasi untuk pengembang lain, atau bahkan menulis UI salin diri Anda, perhatikan beberapa praktik terbaik aksesibilitas mendasar, karena mereka melengkapi semua saran lain untuk penulisan teknis.

Hal-hal seperti:

Andy Bell menawarkan beberapa relatif hal-hal kecil yang dapat Anda lakukan untuk membuat konten lebih mudah diakses, dan ada baiknya Anda memeriksanya. Dan, hanya untuk iseng, John Rhea memamerkan beberapa trik pengeditan yang rapi yang mungkin saat kita bekerja dengan elemen HTML semantik.

Kesimpulan

Itu adalah enam cara yang menunjukkan bagaimana penulisan dan pengembangan teknis bertepatan. Meskipun contoh dan saran mungkin bukan ilmu roket, saya harap Anda menganggapnya berguna, apakah itu berkolaborasi dengan pengembang lain, mempertahankan pekerjaan Anda sendiri, harus menulis salinan Anda sendiri dalam keadaan darurat, atau bahkan menyusun proposal proyek, antara lain sesuatu.

Intinya: mengasah keterampilan menulis Anda dan memberikan sedikit usaha ekstra dalam tulisan Anda sebenarnya dapat membuat Anda menjadi pengembang yang lebih baik.

Sumber daya penulisan teknis

Jika Anda tertarik dengan penulisan teknis:

Jika Anda tertarik dengan copywriting:

Jika Anda tertarik dengan mikrokopi:

Jika Anda tertarik menggunakan panduan gaya profesional untuk meningkatkan tulisan Anda:

Jika Anda tertarik menulis untuk aksesibilitas: