Dalam karir saya sebagai advokat pengembang, penyelenggara konferensi, dan penulis teknis, saya telah menghabiskan banyak waktu untuk membantu pengembang berkomunikasi. Saya telah melihat apa yang berhasil dan apa yang tidak. Ketika komunikasi gagal, sering kali karena pengembang berbicara kepada diri mereka sendiri, bukan kepada pendengar—kegagalan empati.
Paling umum, saya melihat empati ini gagal secara spektakuler dalam dokumentasi perangkat lunak. Dokumentasi memungkinkan pengembang untuk mendalami aspek teknis dari produk yang mereka buat, sesuatu yang mereka habiskan berbulan-bulan jika tidak bertahun-tahun dalam hidupnya. Namun, terlalu sering, pengembang terlalu mendalami hal yang salah, lebih fokus pada produk itu sendiri daripada pada bagaimana orang akan menggunakannya.
Dalam artikel ini, saya membahas tiga kesalahan umum teratas yang saya lihat ketika pengembang menulis dokumentasi, dan menjelaskan bagaimana kesalahan umum ini dapat diperbaiki dengan berempati dengan pengguna Anda.
Lupa bahwa pengembang ingin melakukan sesuatu
Dalam bukunya Badass: Membuat Pengguna Mengagumkan, Kathy Sierra menunjukkan bahwa sangat sedikit pengguna yang ingin menggunakan perangkat lunak. Sebaliknya, mereka ingin melakukan hal-hal yang dimungkinkan oleh perangkat lunak. Misalnya, apakah Anda ingin menggunakan aplikasi setoran cek seluler, atau Anda ingin menyetor cek dan aplikasi setoran cek seluler adalah bagaimana Anda melakukannya?
Perangkat lunak—dan lebih jauh lagi, dokumentasi perangkat lunak—adalah gesekan dalam kehidupan pengguna kami. Pengguna tidak ingin membeli perangkat lunak Anda, dan mereka tidak ingin membaca dokumentasi Anda—mereka hanya ingin masalah mereka terpecahkan. Memahami dan berempati dengan ini akan membantu Anda membuat produk perangkat lunak yang lebih baik dan menulis dokumentasi perangkat lunak yang lebih baik.
Salah satu cara untuk mengatasinya adalah dengan membuat kasus penggunaan untuk produk dan fitur yang Anda kembangkan. Sebuah use case harus berisi:
- Persona pengguna Anda: Siapa pengguna Anda dan apa yang sudah mereka ketahui
- Sasaran pengguna Anda: Apa yang ingin dilakukan pengguna Anda dengan produk Anda
Kasus penggunaan menjelaskan bagaimana seseorang menggunakan perangkat lunak Anda untuk mencapai tujuan tertentu. Seperti yang Anda ketahui dari pengalaman Anda sendiri, tidak semua pengguna perangkat lunak itu sama—kita semua datang dengan model mental, pengalaman, dan kebutuhan yang berbeda. Buat beberapa kalimat untuk setiap poin-poin di atas untuk membantu Anda menjangkau proyek Anda dan berempati dengan pengguna Anda. Kemudian, ketika Anda mulai menulis dokumentasi, Anda akan tahu untuk siapa Anda menulis.
Contoh persona pengguna adalah perangkat lunak yang memiliki peran administrator dan pengguna. Administrator melakukan hal-hal seperti mengkonfigurasi perangkat lunak untuk lingkungan perusahaan, mengatur izin pengguna, dan memperbarui perangkat lunak sesuai kebutuhan. Seorang administrator membutuhkan instruksi konfigurasi dan pengaturan yang jauh lebih luas daripada pengguna harian. Pengguna harian membutuhkan lebih banyak dokumentasi tingkat produk daripada administrator. Administrator tidak perlu tahu cara menyalin beberapa kolom di seluruh sheet, dan pengguna tidak perlu tahu cara mengonfigurasi SSO.
Dokumentasi yang baik berarti menulis untuk kasus penggunaan yang sesuai dengan kebutuhan persona pengguna perangkat lunak Anda yang paling mungkin. Administrator memerlukan dokumentasi seperti “Mengonfigurasi dengan proxy” dan “Mengisi daftar kontrol akses”, yang tidak dilakukan oleh pengguna. Setiap use case menjawab pertanyaan yang berhubungan dengan pekerjaan aktual seseorang: “Bagaimana cara menginstal ini? Bagaimana cara mengamankan ini? Bagaimana cara mengetahui apa yang salah?”
Sangat mudah untuk terganggu oleh semua hal yang ingin Anda sampaikan kepada seseorang dalam kasus penggunaan tertentu. Pertimbangkan bahwa 80% orang yang membaca dokumentasi Anda hanya menginginkan atau membutuhkan 20% dari apa yang Anda ketahui. Sebelum Anda membahas kasus tepi dan situasi yang tidak biasa, pastikan Anda terlebih dahulu memenuhi kebutuhan sebagian besar pengguna Anda.
Masalah “tombol konfirmasi”
Kesalahan umum yang kami buat saat menulis dokumentasi perangkat lunak adalah mendeskripsikan Apa antarmuka, alih-alih bagaimana dari alur kerja pengguna. Saya menyebut ini sebagai masalah tombol konfirmasi. “Klik Tombol Konfirmasi untuk mengonfirmasi” secara teknis adalah dokumentasi, tetapi tidak membantu siapa pun menyelesaikan tugas; itu hanya menggambarkan antarmuka. Anda mungkin berpikir ini lebih jarang terjadi dengan dokumen yang lebih berfokus pada pengembang, tetapi saya rasa jika Anda melihat dokumen API Anda, ada bidang “Nama Pengguna” dengan deskripsi yang mengatakan “Nama Pengguna.”
Perjalanan pengguna
Perjalanan pengguna adalah bagaimana seseorang tanpa pengalaman Anda dengan produk tersebut menemukannya. Perjalanan ini bisa menjadi cara yang berguna untuk menulis dan mengatur konten Anda. Logika ini memberi kita panduan “Mulai Cepat”. Siapa pun yang menjual perangkat lunak, kamera, atau blender yang baru saja Anda buka, tahu bahwa Anda tidak akan membaca semua dokumentasi, jadi mereka memberi Anda hal-hal penting segera setelah Anda membuka kotaknya.
Saat Anda semakin terbiasa dengan alat ini dan ingin melampaui pengaturan otomatis, Anda akan menggali detail yang lebih baik yang dijelaskan dalam dokumentasi lengkap. Jika Anda memiliki masalah atau menginginkan fitur, Anda dapat menghubungi dukungan. Ketika Anda mendapatkan informasi yang cukup, Anda berhenti. Mendapatkan seseorang hanya informasi yang mereka butuhkan, pada waktu yang tepat, lebih penting dan berguna daripada membaca semua dokumen.
Pada akhirnya, tidak ada perangkat lunak (kecuali mungkin COBOL) yang abadi, jadi ada saatnya pengguna berhenti menggunakan produk dan perangkat lunak tersebut dihapus, dihapus, atau diganti. Rencana dokumentasi Anda perlu menyertakan apa yang terjadi pada dokumen setelah masa pakainya yang berguna. Apakah Anda tahu apa yang terjadi pada produk Anda setelah diadopsi? Bisakah Anda menggambarkannya? Apakah orang memiliki cara untuk mengeluarkan data mereka?
Mengirim bagan organisasi Anda
Akhirnya, ada masalah yang dijelaskan oleh Hukum Conway: jangan kirimkan bagan organisasi Anda. Yang kami maksud dengan ini adalah bahwa perangkat lunak (dan dokumentasi) ditulis sesuai dengan struktur organisasi tempat kami bekerja, dan bukan dalam pola penggunaan yang dibutuhkan pengguna. Jika tim penginstal memiliki staf yang berbeda dari tim pemecahan masalah, kebutuhan pengguna mungkin berada di antara tim, dengan tidak ada tim yang bertanggung jawab untuk memecahkan masalah pengguna.
Setiap tim menulis apa yang paling mereka ketahui—fitur mereka sendiri—tanpa mendokumentasikan bagaimana fitur-fiturnya, mereka hanya menulis tentang itu dan bukan tentang bagaimana fitur-fitur tersebut saling beroperasi atau bagaimana fitur-fitur tersebut dapat mengalir satu sama lain dalam ruang hari kerja pengguna.
Dokumentasi yang dihasilkan terlihat seperti:
- Produk unggulan:
- Fitur 1 dokumentasi
- Ikhtisar Fitur 1
- Cara menggunakan Fitur 1
- Fitur 2 dokumentasi
- Ikhtisar Fitur 2
- Cara menggunakan Fitur 2
- Fitur 3 dokumentasi
- Ikhtisar Fitur 3
- Cara menggunakan Fitur 3
- Fitur 1 dokumentasi
Struktur ini bagus dan rapi di permukaan, tetapi mengharuskan pengguna untuk menyaring dan mengumpulkan terlalu banyak konten yang berbeda untuk menyelesaikan masalah mereka. Ketika Anda mengatur berdasarkan bagaimana sesuatu dibangun, itu tidak berhubungan dengan apa yang perlu diketahui pengguna saat ini: bagaimana memecahkan masalah langsung mereka.
Jika produk Anda memiliki beberapa persona pengguna dan perjalanan pengguna yang berbeda, terkadang sulit untuk mengoordinasikan transisi tersebut. Namun, saya telah menemukan bahwa jika Anda memberi orang persona dan cerita untuk ditindaklanjuti melalui produk, mereka memahami mengapa Anda perlu menulis untuk tugas yang dimiliki orang alih-alih cara produk dibuat. Manusia menyukai cerita dan akan berempati jika diberi cara untuk melakukannya. Anda hanya perlu membantu menciptakan hubungan antara perangkat lunak yang Anda tulis dan orang-orang yang akan menggunakannya.
Dokumentasi empatik adalah dokumentasi yang berhasil
Menumbuhkan empati untuk orang yang menggunakan produk Anda sangat penting untuk keberhasilannya, dan dokumentasi adalah salah satu area di mana Anda dapat menunjukkan empati itu. Memikirkan dengan cermat tentang siapa pengguna Anda dan apa yang mereka butuhkan dari dokumentasi Anda tidak hanya membuat proses penulisan lebih mudah dan lebih intuitif, tetapi juga membantu pengguna mendapatkan nilai lebih dari produk Anda.
—-
Jika Anda ingin lebih banyak saran penulisan yang disesuaikan untuk pengembang, lihat buku yang saya tulis bersama: Dokumen untuk Pengembang: Panduan Lapangan Seorang Insinyur untuk Penulisan Teknis.
Tags: dokumentasi, empati