Pada musim gugur 2016, kolega saya dan saya diperintahkan untuk memperbaiki dokumentasi dan konten di perusahaan saya sebelumnya. Kami menghabiskan satu tahun di semua jenis dokumentasi: referensi API, panduan, tutorial, posting blog. Sebelum itu, saya menulis dok selama 5 tahun, tetapi saya tidak secara resmi mempelajari ini. Tapi saya tidak bisa disebut tidak berpengalaman: selain mendokumentasikan API untuk proyek dan startup, saya juga mengajar Python Flask di seminar sambil belajar di kursus terakhir di universitas. Tetapi sekarang ini adalah kesempatan untuk fokus hanya pada bisnis favorit saya: untuk membantu spesialis di semua tingkatan melalui dokumentasi teknis.

Tahun ini saya belajar banyak dari komunitas Write The Docs, dari penyedia API lainnya, dan metode coba-coba. Tahun lalu, saya berbagi pengalaman saya dalam laporan "Apa yang Saya Ingin Tahu tentang Menulis Dokumentasi" di Portland API Strategy and Practice Conference. Artikel ini adalah ikhtisar dari pengetahuan yang diperoleh.

Bagaimana orang benar-benar membaca dokumentasi?

"Sebuah bangsa bergidik pada sebuah fragmen besar dari satu teks", foto oleh The Onion

Apakah Anda tahu perasaan ini seperti dalam gambar? Itu terjadi. Mungkin tidak secara fisik, tetapi kemungkinan besar, orang bergidik mental. Saya terus-menerus tersiksa oleh pikiran bahwa orang tidak akan membaca teks saya kecuali saya membuatnya dengan cara yang mudah dicerna. Astaga, ini bisa terjadi bahkan dengan artikel ini.

Dalam penelitian Neilson Norman Group 2006, 232 pengguna melihat ribuan halaman web. Ternyata pengguna biasanya melihat halaman menggunakan pola-F:

“Pertama mereka membaca dalam arah horizontal , biasanya di bagian atas area konten. Ini adalah elemen teratas dari gambar F. "
“Kemudian mereka bergerak sedikit ke bawah halaman - dan membuat gerakan horizontal kedua , yang biasanya mencakup area yang lebih pendek dari yang sebelumnya. Elemen tambahan ini membentuk elemen tengah dari gambar F ".
“Akhirnya, pengguna memindai sisi kiri konten secara vertikal . Terkadang ini adalah pemindaian yang lambat dan sistematis, yang ditampilkan sebagai strip padat pada peta panas. Terkadang gerakannya lebih cepat, membentuk bintik-bintik pada peta panas. Ini adalah elemen vertikal terakhir pada gambar F. "

Heatmaps Nielsen Norman Group

Studi ini menemukan beberapa pola pemindaian alternatif, seperti pola kue puff, peta jerawatan, template layout, pola bypass, dan pola yang bertujuan. Saya sangat menyarankan Anda membaca laporan .

Penting untuk dicatat bahwa pola-F menghalangi pengguna , tetapi posisi konten yang baik membantu mencegah pemindaian-F.

Apa implikasi spesifik untuk dokumentasi?

Dua paragraf pertama harus menunjukkan informasi yang paling penting.
3-5 kata pertama sangat penting
Judul, paragraf, dan daftar berpoin dengan kata-kata informatif
Perubahan font (ukuran, tautan, cetak tebal, dll.) Mungkin diperlukan untuk menjaga perhatian pembaca

Jadi bagaimana cara menyusun konten pada halaman?

Cegah pemindaian: pastikan informasi yang dibutuhkan pembaca disorot
Satu pemikiran di paragraf. Jika ada beberapa, pecahkan paragraf
Pengguna melewatkan semua yang tampak seperti spanduk, jadi berhati-hatilah dengan ilustrasinya.
Jangan memperluas kolom teks terlalu banyak: secara optimal 65–90 karakter

Saya belajar beberapa tips ini dari ceramah Kevin Burke , "Cara Menulis Dokumentasi untuk Pengguna yang Tidak Membacanya." Kevin mendukung dokumentasi Twilio dari 2011 hingga 2014.

Selain itu, paragraf memiliki spesifikasi sendiri. Seperti teks The Onion , ketika Anda membaca banyak paragraf, Anda dapat melewatkan intinya. Lalu mengapa sering menggunakannya? Mari kita lakukan percobaan dari dokumentasi IO Keen:

Cepat baca ini:

Set acara dapat memiliki hampir semua nama, tetapi ada beberapa aturan: nama tidak boleh lebih dari 64 karakter. Seharusnya hanya berisi karakter ASCII. Tidak boleh nol.

Sekarang cepat baca ini:

Set acara dapat memiliki hampir semua nama, tetapi ada beberapa aturan:

Judul tidak boleh lebih dari 64 karakter
Seharusnya hanya berisi karakter ASCII
Tidak boleh nol

Dalam kedua contoh, teks yang sama persis . Ini bukan binom Newton: yang kedua membantu menyerap informasi dengan lebih baik dan lebih cepat. Jika paragraf berisi daftar jenis apa pun, ubahlah menjadi daftar berpoin.

Nanti kita akan membahas secara lebih rinci tata letak dokumentasi dan navigasi di atasnya.

Contoh kode

Apa itu dokumentasi API tanpa kode, kan? Ada banyak contoh kode di banyak dokumen kami, dan pengguna benar-benar membacanya. Tetapi masalahnya adalah mereka tidak selalu memperhatikan teks di sekitarnya.

Konteks dalam kode sampel sangat penting untuk keberhasilan pengembang. Pengembang senang menyalin dan menempel dengan cepat. Berikut adalah contoh dengan API IO Keen:

var client = new Keen({ projectId: "your_project_id", writeKey: "your_write_key" }); var ticketPurchase = { price: 50.00, user: { id: "020939382", age: 28 }, artist: { id: "19039", name: "Tycho" } } client.addEvent("ticket_purchases", ticketPurchase);

Pengembang dengan cepat menyalin dan menempelkan kode ini. Dan ...

Pertama, bagaimana mereka menjalankan file sama sekali? Mungkin seperti node file_name.js , tetapi ini tidak ada dalam kode. Orang bisa menunjukkan dalam komentar di atas.

Yah, mereka memulainya dan ... ReferenceError: Keen is not defined . :-( Klien Keen tidak diinisiasi, di bagian atas tidak ada impor atau memerlukan pernyataan, dan itu hanya berfungsi setelah menginstal perpustakaan npm.

Pengguna memperbaikinya dan menjalankannya lagi ... Tebak ?! Kesalahan lain! your_project_id dan your_write_key hilang.

Semua ini bisa dibuat lebih jelas.

Berikut adalah contoh dari dokumentasi Twilio yang memberikan konteks yang baik untuk pengguna akhir:

Cuplikan layar dari dokumentasi perpustakaan Twilio Node Helper

Ini segera menjelaskan cara menginstal perpustakaan, menanamkannya dalam kode Anda dan apa yang perlu diganti dalam kode sampel sebelum menjalankannya.

Salin dan tempel bug

Karena kami memiliki banyak kode sampel dalam dokumentasi, salin-tempel yang sukses adalah properti yang cukup penting. Berikut adalah dua contoh di mana ini tidak dihormati:

 #      $ gem install rails

Tampaknya tidak berbahaya, kan? Pikirkan lagi, apa yang terjadi ketika Anda menyalin dan menempel ini ke baris perintah? Anda kemungkinan besar akan menerima:

 bash: command not found: $

Kesalahan umum. Entah Anda ingin perintahnya terlihat seperti pada baris perintah, atau Anda tidak sengaja menyalinnya. Saya akan merekomendasikan memberikan $ . Anda juga dapat menemukan cara untuk melarang copy-paste simbol ini sehingga kesalahan tidak mengganggu pengguna.

Contoh yang lebih baru: apakah Anda memeriksa betapa mudahnya menyoroti kode yang ingin disalin pengguna?

Kelsey Hightower berjuang untuk menyalin kode sampel dari StackOverflow di presentasi Google Cloud Next.

“Copy programmer bagus, paste programmer hebat”

Apakah dia sengaja melakukannya? Kami tidak akan pernah tahu. Namun, ini adalah ilustrasi tentang bagaimana programmer mencoba menyoroti blok teks besar di beberapa situs dokumentasi. Pastikan antarmuka pengguna situs memudahkan untuk menyalin blok besar. Anda bahkan dapat memecah blok-blok ini untuk menjelaskan fragmen secara individual. Sehingga mereka akan menjadi lebih mudah diakses untuk disalin dan dipahami.

"Itu saja!"

"Itu saja!" Ungkapan ini tampaknya tidak berbahaya di luar konteks, tetapi bayangkan bagaimana kata-kata tertentu seperti "mudah", "sederhana", "sepele" dan "tidak rumit" dirasakan ketika Anda memiliki masalah - tidak hebat! Ketika seseorang terjebak mencoba untuk membuat API berfungsi, frasa seperti itu menimbulkan keraguan pada kecerdasannya dan membuatnya mengajukan pertanyaan: "Jadi aku bodoh?" Ini melemahkan semangat.

Penyederhanaan berlebih

Penyederhanaan adalah hal biasa. Ini paling umum di kalangan pemula dalam menulis dokumentasi. Seringkali, penulis dokumentasi pada saat yang sama adalah pengembang sistem, sehingga beberapa hal tampak “mudah” bagi mereka. Tetapi mereka mengembangkan fungsi ini, menulis kode untuk itu, memeriksanya berkali-kali, dan kemudian menulis dokumentasi. Saat Anda melakukan sesuatu puluhan kali, jelas bahwa itu akan "mudah" bagi Anda. Tetapi bagaimana dengan seseorang yang belum pernah melihat UI atau fungsi sebelumnya?

Empati

Pilihan kata sangat penting. Empati adalah kemampuan untuk memahami dan berbagi perasaan orang lain. Ketika kami menunjukkan empati, kami membantu tidak hanya pendatang baru, tetapi juga pengguna yang lebih maju. Ini membantu meningkatkan potensi jumlah pengguna, kasus penggunaan, pelanggan, dan bahkan pendapatan perusahaan.

Tetapi ketika dokumentasi ditulis oleh pengembang proyek pakar, empati lebih sulit. Berikut adalah beberapa tips bermanfaat yang telah membantu saya di masa lalu:

Mintalah peserta proyek yang kurang berpengalaman untuk mengomentari dokumentasi dengan jujur.
Dorong peserta proyek yang kurang berpengalaman untuk berkontribusi atau menunjukkan poin-poin dokumentasi yang tidak mereka pahami.
Ciptakan lingkungan di mana pertanyaan didorong, termasuk yang mungkin tampak "jelas" bagi peserta proyek yang berpengalaman - ini akan membantu Anda memperhatikan "blind spot"
Gunakan pemroses kode dalam tinjauan kode dan proses CI untuk menjamin empati dan keramahan bahasa untuk semua pengguna.
Akhirnya, minta komentar pada dokumentasi pengguna nyata, tunjukkan teksnya dan tanyakan apakah semuanya jelas

Pesan kesalahan sebagai semacam dokumentasi

Biasanya, pengguna lebih cenderung melihat pesan kesalahan daripada dokumentasi. Menurut Kate Voss, "pesan kesalahan sebenarnya adalah kesempatan." Saya percaya bahwa banyak pengembang dokumentasi kehilangan kesempatan ini. Ada tempat untuk pelatihan, membangun hubungan saling percaya dan harapan pengguna. Pertama-tama, Anda akan membantu orang membantu diri mereka sendiri.

Kate at Write The Docs menyediakan banyak informasi bermanfaat tentang menulis pesan kesalahan. Saya belajar banyak selama pekerjaan saya sebelumnya tentang pesan kesalahan API, serta berada di sisi lain dari barikade, menerima pesan kesalahan dari API lain sebagai pengembang.

Kate mengatakan bahwa pesan kesalahan yang baik dibangun di atas tiga prinsip:

Kesederhanaan
Kemanusiaan
Kegunaan

Kesederhanaan

Anda harus segera meminta maaf, meskipun itu bukan kesalahan Anda. Saya juga berlatih ini di layanan dukungan.

Contoh:

Maaf, tidak dapat terhubung ke ___. Silakan periksa pengaturan jaringan Anda, sambungkan ke jaringan yang tersedia, dan coba lagi.

Kemanusiaan

Gunakan istilah yang bisa dibaca manusia; hindari frasa seperti "pengecualian yang dilemparkan oleh target panggilan." Saat menulis kode yang memicu banyak pesan kesalahan, mudah untuk lolos dengan kosakata yang jelas.

Contoh (Kesalahan kode status Twilio 401):

 { “code”: 20003, “detail”: “Your AccountSid or AuthToken was incorrect.”, “message”: “Authenticate”, “more_info”: “https://www.twilio.com/docs/errors/20003", “status”: 401 }

Kegunaan

Jika Anda ingat salah satu tips ini, ingatlah kegunaannya. Bagikan informasi dengan pengguna tentang cara mengatasi masalah.

Contoh:

Maaf, gambar yang Anda coba unggah terlalu besar. Coba lagi dengan gambar yang lebih kecil dari 4000px dan lebarnya 4000px.

Cara menulis pesan kesalahan

Seperti halnya dokumentasi lainnya, berikan informasi penting terlebih dahulu. Ini bisa dilakukan dengan menentukan objek terlebih dahulu, lalu aksinya. Pengguna mencari hasil, bukan bagaimana menuju ke sana. Ini berguna ketika pengguna dengan cepat memindai pesan kesalahan.

Contoh buruk:

Tekan tombol kembali untuk kembali ke halaman sebelumnya.

Contoh yang bagus:

Untuk kembali ke halaman sebelumnya, gunakan tombol kembali.

Pesan Kesalahan Dokumentasi

Saya merasa sangat berguna ketika pesan kesalahan API umum disebutkan dalam dokumentasi. Dengan cara ini, penulis dokumentasi dapat mengklarifikasi pesan kesalahan tanpa memperbesar dokumentasi, sementara pada saat yang sama membantu pengguna memahami mengapa kesalahan terjadi.

Twilio menerbitkan katalog lengkap kesalahan dan peringatan dengan kemungkinan penyebab dan solusi. Dengan menggunakan metode ini, Anda dapat membuat pesan kesalahan yang sebenarnya lebih pendek, tetapi tetap bermanfaat.

Dalam hal kesalahan 20003 (kesalahan kode status 401, disebutkan sebelumnya), ada banyak kemungkinan alasan yang secara jelas dinyatakan dalam katalog.

Sumber: https://www.twilio.com/docs/api/errors

Stripe melakukan sesuatu yang mirip dengan deskripsi terperinci dari berbagai kode kesalahan.

Sumber: https://www.twilio.com/docs/api/errors

Anda bahkan dapat menemukan pesan kesalahan Anda di pertanyaan StackOverflow. Jawab mereka secara sederhana, manusiawi dan dengan manfaat. Karena SEO, pengguna sering berakhir dengan pesan kesalahan Anda di StackOverflow daripada dokumentasi yang sebenarnya.

Petunjuk: jika seseorang tidak merespons dengan rendah hati, manusiawi dan dengan manfaat, maka dengan "reputasi" yang cukup, Anda dapat mengedit jawaban StackOverflow.

Pemilihan kata

Banyak kata memiliki pola mental yang mapan. Misalnya, kata-kata seperti "perpustakaan", SDK, "pembungkus" dan "klien" sudah kelebihan beban dan melewati perhatian pembaca.

Dalam ceramahnya, "Bahkan untuk ceramah ini, sulit untuk menemukan nama" di Write The Docs, Ruthie Bendor mengatakan mengapa memilih kata yang tepat bisa sangat sulit.

Kita sering memilih kata-kata yang buruk, walaupun saat menulis teks kita melakukan ini sepanjang waktu. Seperti banyak judul SDK, setiap kata membangkitkan berbagai perasaan, ide, dan definisi dalam pembaca. Anda mungkin tidak memahami ini - dan seringkali kami membuat asumsi yang salah.

Dalam situasi seperti itu, pepatah yang terkenal itu benar dan belum pernah terjadi sebelumnya: "Hanya ada dua tugas sulit di bidang ilmu komputer: pembatalan cache dan penemuan nama." Kutipan ini sering dikreditkan ke Phil Carleton, tetapi hari ini ada banyak variasi ungkapan ini. Terkadang pada akhirnya mereka menambahkan "... dan kesalahan per unit". Ruti menganggap ini sebagai demonstrasi bahwa perangkat lunak saat ini sebagian besar didasarkan pada kode atau pekerjaan orang lain.

Mengapa nama objek buruk (atau dokumentasi) dipertahankan?

Seperti penyederhanaan berlebihan, kita sering tidak mengerti bahwa nama itu buruk. Inilah yang disebut Ruthie sebagai kegagalan empati . Ini adalah bagaimana mengatakan bahwa masalah kata-kata yang tidak berhasil tidak menjadi perhatian saya, oleh karena itu tidak ada.

Petunjuk untuk AS: Untuk mencegah rasisme yang tidak disengaja, gunakan kata-kata "daftar terlarang" dan "daftar yang diperbolehkan" alih-alih "hitam" dan "putih".
(Sumber: Andre Staltz dan rel / rails / issues / 33677 )

Itu masih mengingatkan saya pada apa yang Ruthie sebut sebagai kesalahan berpikir pemula . Itu seperti mengatakan "Ini sepenuhnya jelas bagi saya. Saya tidak mengerti bagaimana seseorang tidak bisa memahami ini. "

Akhirnya, Ruthie menyebutkan kesalahan lokalisasi . Misalnya, kata Bing dalam bahasa Cina berarti "sakit."

Menurut studi Survei Sumber Terbuka GitHub 2017 :

Hampir 25% pengembang membaca dan menulis bahasa Inggris tidak "sangat baik." Saat berkomunikasi dalam suatu proyek, gunakan bahasa yang dapat dimengerti dan dapat diakses untuk orang-orang dari negara-negara yang tidak berbahasa Inggris.

Apakah Anda memperhitungkan ini ketika menggunakan Americanisms dan idiom dalam dokumentasi? Banyak dari mereka mungkin tidak dapat dipahami oleh pengguna.

Petunjuk: Saya sangat yakin bahwa salah satu "trik" terbesar untuk menyelesaikan masalah ini adalah keanekaragaman tim dokumentasi.

Masih ada kasus ketika kita mengakui kesalahan, tetapi kita tidak bisa atau tidak ingin memperbaikinya, karena kita ...

Terikat padanya
Kami tidak menemukan waktu
Kami tidak melihat pentingnya
Kami tidak memiliki agen untuk memperbaikinya.

Anda dapat mengatakan atau mendengar: "Tapi ini adalah gagasan saya!", "Siapa yang mengambil kekasihku?" "Jika kita mengganti nama, semuanya akan hancur", "Aku tidak percaya bahwa mengubah nama ini akan memengaruhi sesuatu yang penting."

Anda tidak perlu takut akan refactoring dan penulisan ulang ketika datang ke dokumentasi. Bagaimana memperbaikinya, jika Anda tidak setuju dengan kenyataan bahwa awalnya bukan pilihan terbaik yang dibuat?

Bagaimana cara memilih kata yang tepat?

Untuk memulai, saya sarankan mengajukan pertanyaan: kata-kata apa yang digunakan pengguna Anda? Lingkaran programmer yang berbeda menggunakan istilah yang berbeda, jangan mencoba menggunakan yang lain. Ini bermanfaat tidak hanya untuk pembaca, tetapi juga untuk pencarian dan SEO.

Pada akhirnya, semuanya pasti menuju penilaian subyektif. Namun, ada beberapa prinsip yang perlu dipertimbangkan. Ruthie mengatakan nama buruk adalah yang bisa:

mempermalukan
kesal
menyesatkan
membingungkan
menyinggung

Nama baik, di sisi lain:

berkontribusi pada klarifikasi mendadak ("itu dia!")
disuntikkan ke dalam konteks
jelaskan
menerangi
berikan dukungan

Saya merekomendasikan untuk mempertimbangkan kualitas-kualitas ini ketika mengurangi dokumentasi untuk membuat ulasan yang berguna dan jujur tentangnya.

Memilih kata yang tepat itu sulit. Tidak ada formula ajaib. Semua pengguna berbeda, seperti halnya kasus penggunaan produk; apa yang berhasil untuk beberapa mungkin tidak bekerja untuk yang lain. Jika mudah, semua orang akan memiliki dokumentasi yang lebih baik. Seperti yang dikatakan Ruthie kepada pengembang: “Program menulis adalah latihan dalam menemukan nama. Atasi itu. " Dan jika Anda menulis dokumentasi untuk program orang lain, "beri tahu pengembang jika namanya tidak mencapai target".

Kami sedang menulis dokumentasi teknis: panduan untuk orang awam