Pendekatan yang Berfokus pada Keputusan, Bukan Tugas

• Berfokus pada keputusan

  • Kutipan dari Every Page Is Page One membawa perubahan besar pada pendekatan penulisan dokumentasi teknis
  • Dalam komunikasi teknis, pembahasan biasanya berfokus pada dukungan tugas, tetapi dalam banyak kasus informasi yang dibutuhkan orang untuk menyelesaikan tugas bukanlah cara kerja mesin, melainkan informasi pendukung pengambilan keputusan
  • Mendokumentasikan prosedur saja tidak cukup
  • Perlu memberi tahu keputusan apa yang harus diambil pengguna, apa konsekuensinya, dan sebisa mungkin mengarahkan mereka ke sumber daya serta referensi yang membantu pengambilan keputusan

Ringkasan GN⁺

• Tulisan ini menekankan pentingnya dukungan pengambilan keputusan dalam penulisan dokumentasi teknis
• Tidak cukup hanya menjelaskan prosedur; yang diperlukan adalah membantu pengguna membuat keputusan yang lebih baik
• Bagi penulis dokumentasi teknis, penting untuk menyediakan konteks dan informasi yang dibutuhkan pengguna
• Untuk proyek di industri dengan fungsi serupa, Confluence dan Notion direkomendasikan

[GN⁺]

Komentar Hacker News

• Menulis tentang birokrasi Jerman, dan saya sepenuhnya setuju dengan pendekatan seperti ini.
  Sebagian besar panduan saya dimulai dengan “ini apa, siapa yang harus melakukannya, dan mengapa harus dilakukan”. Jika kita tidak memastikan orang melakukan hal yang tepat dengan alasan yang tepat, mereka bisa melenceng sangat jauh ke arah yang salah.
  Kebanyakan situs web pemerintah tidak menjelaskan hal-hal seperti ini, dan hanya meminta apa yang diperlukan untuk menyelesaikan prosedur yang menjadi tanggung jawab mereka. Mereka tidak melihatnya sebagai bagian dari keputusan yang lebih besar, dan mengasumsikan pengguna datang karena sudah tahu apa yang sedang mereka lakukan.

  • Terkait paragraf terakhir, situs web gov UK melakukan bagian ini dengan sangat baik. Ada landing page yang menjelaskan prosedurnya, lalu peringatan dan hal-hal yang perlu diperhatikan muncul terlebih dahulu sebelum Anda bisa benar-benar mengisi formulir.
    Jika membuka hasil Google untuk perpanjangan SIM, https://www.gov.uk/renew-driving-licence, lalu menekan “Start Now”, Anda akan mengerti maksudnya.
    Dari sudut pandang “power user”, kadang terasa seperti hambatan, tetapi saya paham bahwa mereka harus mempertimbangkan semua orang.
  • Melihat komentar ini, sepertinya Anda akan menyukai Every Page Is Page One. Intinya adalah orang bisa masuk ke situs dokumentasi dari halaman mana pun, jadi setiap halaman harus cepat memberi konteks dan membuat pengguna mudah menilai apakah mereka berada di jalur yang benar.
    Judul bukunya juga berasal dari sini. Halaman mana pun di sebuah situs bisa menjadi halaman pertama bagi pengguna.
  • Saya berharap pendekatan seperti ini ada di lebih banyak dokumentasi teknis. Saya cenderung terus bertanya-tanya mengapa sesuatu dilakukan dengan cara tertentu, sehingga sering terseret ke percabangan topik dan jadi lebih lambat.

• Ini cocok dengan cara menggunakan LLM. Saya selalu meminta opsi, lalu memutuskan sendiri mana yang paling masuk akal.
  Pada dasarnya saya menggunakannya seperti semacam dokumen ajaib yang aneh, yang pada setiap momen pengambilan keputusan memuntahkan opsi-opsi yang mungkin, tidak sempurna tetapi berguna.

  • Bayangkan murid magang yang bekerja di bawah seniman terkenal seperti Leonardo. Sang master menggambar garis besar dan sketsa, lalu para murid mengisi bagian kosong di bawah pengawasan. Kadang sang master juga mencuri ide dari para muridnya.
  • Bisa berikan satu contoh cara ini?

• Benar-benar bagus. Singkat, tepat sasaran, dan penuh insight. Saya cenderung berpikir dengan melihat gambaran besar, jadi bagi saya bukan hanya cara melakukan sesuatu yang penting, tetapi juga mengapa, serta bagaimana hal itu terhubung dengan konteks yang lebih besar.
  Saya mendorong para developer untuk aktif menggunakan kolom Description pada story dan task Jira, agar memuat ringkasan tentang mengapa kita melakukan pekerjaan ini dan bagaimana ia terhubung ke gambaran besar. Sebagian tampaknya tidak suka, tetapi sebagian lainnya cukup menyukainya.
  Saya senang karena bisa menyediakan gambaran besar proyek, dan para developer puas karena dengan memahami gambaran besar itu mereka bisa bekerja lebih mandiri.

• Mengukur apakah dokumentasi membantu orang mengambil keputusan yang baik tampaknya jauh lebih sulit daripada mengukur apakah dokumentasi membantu mereka berhasil menyelesaikan tugas.
  Alasan mengoptimalkan dokumentasi berbasis tugas dan prosedural adalah karena perusahaan meminta tim dokumentasi membuktikan nilainya, ada permintaan untuk jenis dokumentasi seperti ini, dan ada banyak cara untuk mengukur serta melaporkannya dalam jangka pendek.
  Namun pertanyaan “apakah kumpulan dokumen ini membantu seseorang membuat hal yang tepat dengan cara yang tepat” adalah sesuatu yang bahkan sulit dijawab organisasi tentang produknya sendiri; jika diabstraksikan sebagai dampak dokumentasi, hasilnya menjadi sangat kabur.
  Bukan berarti kita tidak bisa menulis dokumentasi yang membantu pengambilan keputusan, melainkan sangat sulit membuktikan dengan angka bahwa kita telah melakukannya. Saya bisa memberi peringkat seberapa baik berbagai kumpulan dokumen mendukung pengguna yang perlu mengambil keputusan dan menjelaskan alasannya, tetapi saya tidak yakin bagaimana mengkuantifikasikannya dengan cara yang diinginkan perusahaan.
  Saya juga penasaran bagaimana struktur kumpulan dokumen yang dirancang untuk mendukung pengambilan keputusan akan berbeda dari dokumentasi yang mendukung tugas. Kategori besarnya mungkin tetap sama: konsep, referensi, dan panduan; tetapi mungkin akan ada jauh lebih banyak dokumen konsep dan lebih banyak ruang untuk mengontekstualisasikan konsep. Saya juga memperkirakan akan ada lebih banyak dependensi antar-topik dan cross-reference.

  • Menarik bahwa pikiran pertama Anda bukan “bagaimana saya bisa memakai ini untuk memperbaiki dokumentasi yang saya tulis”, melainkan “bagaimana saya membuktikan bahwa ini memperbaiki dokumentasi yang saya tulis”. Sepertinya Anda bekerja di lingkungan yang cukup ketat.
  • Di tempat yang memberi kebebasan untuk melakukan apa yang menurut kita terbaik bagi pengguna, seperti proyek pribadi, kemungkinan besar dukungan keputusan akan dijadikan dasar strategi dokumentasi.
    Dari sudut pandang bekerja dengan integritas, jika saya merasa “dukungan keputusan” adalah yang terbaik untuk proyek saya, saya mungkin berkewajiban membawa strategi ini juga ke dokumentasi kerja.
    Untungnya saya tidak sedang dicekik oleh manajer berpandangan sempit, tetapi jika harus meyakinkan orang di tempat kerja, saya mungkin akan melakukannya begini. Pertama, jelaskan logika strateginya. Dukungan keputusan masuk akal dan juga persuasif. Dokumentasi tugas tetap ditulis, tetapi tugas hanyalah subset dari dukungan keputusan.
    Lalu berikan daftar panjang contoh dari tiket support, diskusi chat room, dan sebagainya, ketika kurangnya dukungan keputusan menjadi masalah. Demi kejujuran intelektual, tampilkan juga daftar lengkap tiket support terkait dokumentasi beserta subset yang terkait dukungan keputusan. Jika porsinya tidak bisa diabaikan, misalnya 25%, maka “dukungan keputusan” perlu dilihat lebih dalam.
    Terakhir, para pemangku kepentingan bisa menyebutkan contoh dari pekerjaan mereka sendiri. Misalnya, “Ingat betapa sulitnya memutuskan CMS apa yang akan kita pakai sebagai pengganti?”

• Biasanya inilah yang saya sebut pendekatan heuristik.
  Saya merasa pekerjaan membutuhkan pendekatan seperti logika fuzzy. Hanya saja, ini paling berhasil ketika engineer sudah punya tingkat pengalaman tertentu.
  Jika pengalamannya kurang, meskipun orangnya kompeten dan pintar, kita harus jauh lebih preskriptif.

  • Thinking in Bets adalah salah satu buku yang paling berguna bagi cara saya mendekati software engineering. Itu bukan buku tentang kode, melainkan tentang cara mengambil keputusan secara efektif dalam lingkungan dengan informasi terbatas.
  • Saya kurang paham apa maksudnya mendekati pekerjaan dengan cara logika fuzzy. Bisa jelaskan sedikit lebih rinci?

• Pendekatan yang baik untuk mengambil keputusan dalam konteks tim dijelaskan Rich Hickey di sini: https://www.youtube.com/watch?v=c5QF2HjHLSE
  Judul talk-nya “Design in Practice”, tetapi isinya sebenarnya tentang pengambilan keputusan.

• “Pekerjaan hanyalah segala sesuatu yang harus dilakukan untuk berpindah dari satu keputusan ke keputusan berikutnya.” — Venkatesh Rao, Tempo

• Saya juga pernah mengemukakan hal serupa. Jangan hanya menjelaskan tool pada tingkat tinggi; khususnya, orang sering masuk ke mode pemasaran, padahal yang perlu dibahas adalah masalah apa yang dirancang untuk diselesaikan oleh tool itu dan trade-off apa yang diambil dalam prosesnya.
  Dengan begitu, jauh lebih mudah menempatkan tool serta pilihan dan mode yang tersedia dalam konteks, lalu cepat menilai apakah itu cocok untuk diri sendiri.

• Saran ini agak membingungkan. Keputusan siapa? Keputusan pembuat tool, atau keputusan pengguna?
  Secara umum ini terlihat seperti penyederhanaan berlebihan. Akan lebih berguna jika terlebih dahulu memahami jenis dokumentasi yang sedang ditulis: untuk pembelajaran, berorientasi tujuan, untuk pemahaman, atau untuk penyampaian informasi [1]
  Misalnya, saat mencari API suatu fungsi, informasi “keputusan” yang membanjir bisa terasa menjengkelkan.
  1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

  • Dokumentasi harus selalu menangani kebutuhan pengguna. Itu tidak hilang. Begitu juga dengan Diataxis, empat kuadran dokumentasi yang disebutkan itu.
    Menurut saya, alasan tulisan ini mendapat resonansi adalah karena ia mengungkap blind spot dari dua strategi yang sudah dikenal. Semua orang berusaha membuat dokumentasi yang berpusat pada pengguna dan banyak tim mengikuti Diataxis, tetapi tetap saja mereka kesulitan menyelesaikan pekerjaan lewat dokumentasi.
    Memulai dari sudut pandang dasar bahwa “dokumentasi harus mendukung keputusan” bisa menjadi jalan untuk membuat dokumentasi lebih berguna.

• Penting untuk mengetahui bagaimana orang menggunakan sistem saya untuk mengambil keputusan. Menurut saya, pengetahuan seperti itu penting untuk memelihara, memperluas, atau membangun ulang sistem.
  Namun tulisan ini mengusulkan tanggung jawab yang lebih tinggi. Yaitu mendokumentasikan proses pengambilan keputusan pengguna, serta memberi tahu konteks, pilihan, dan konsekuensi dari keputusan.
  Saya pernah bekerja pada “sistem pendukung keputusan” yang memiliki tanggung jawab seperti itu, dan kompleksitasnya meningkat sangat cepat. Orang suka memperdebatkan hasil meskipun hasilnya diketahui 100% pasti. Mereka juga tidak suka email otomatis yang memuat ketidakpastian, dan tidak suka ketika dokumentasi memaksa pilihan biner padahal di dunia nyata ada jauh lebih banyak opsi.
  Di luar tulisan ini, saya berharap bukunya membahas konsep kontrol. Agar suatu perilaku bisa didokumentasikan, harus ada tingkat jaminan atau pemaksaan tertentu atas perilaku itu agar dokumentasi dapat mempertahankan otoritasnya. Secara pribadi, saya melihat ketiadaan otoritas dan kontrol sebagai blind spot yang umum dan besar dalam inisiatif penulisan seperti https://www.plainlanguage.gov.

  • Mengutip kembali apa yang pernah saya tulis tentang tulisan ini di r/technicalwriting, hal yang benar-benar penting dalam ide Baker adalah bahwa doktrin pendidikan dokumentasi teknis benar-benar sangat berfokus pada tugas.
    Jika mensurvei para penulis dokumentasi teknis profesional, banyak dari mereka mungkin percaya bahwa “membantu pengguna menyelesaikan tugas” adalah tujuan utama dokumentasi, bahkan mungkin TUJUAN utama.
    Kutipan singkat Baker cukup radikal dalam arti Latin, yaitu “kembali ke akar”, karena ia menyiratkan bahwa salah satu asumsi dasar kita sangat kurang.
    Secara pribadi, alasan ide Baker menarik bagi saya adalah karena ia menetapkan standar yang jauh lebih tinggi daripada standar yang saat ini diharapkan dari dokumentasi teknis. Banyak dokumentasi berasumsi bahwa begitu tugas sudah didokumentasikan, “misi selesai”, tetapi Baker tampaknya mengatakan bahwa itu saja belum cukup.
    Tugas tentu tetap harus didokumentasikan, tetapi tugas adalah subset dari informasi yang membentuk keputusan.
    Saya tidak ingat apakah buku Baker membahas kontrol dengan cara yang disebutkan di sini. Bagi saya itu ide baru, jadi terima kasih.
    Contoh kontrol konkret yang terlintas adalah seperti ini. Sebagian besar dokumentasi saya bergantung pada halaman proyek open source lain; jika kualitas halaman eksternal itu rendah, besar kemungkinan memperbaiki dokumentasi itu juga harus menjadi tanggung jawab saya. Banyak orang mungkin menganggap dokumentasi di luar situs mereka bukan tanggung jawab mereka, tetapi jika benar-benar ingin mendukung keputusan, siapa yang meng-host dokumentasi itu tidak penting.
    Mungkin ada banyak hal yang bisa dipelajari dari sikap menjadi warga open source yang baik.