- Berangkat dari premis bahwa dokumentasi teknis harus memainkan peran yang berbeda sesuai situasi pengguna, Diátaxis adalah pendekatan yang menata konten, struktur, dan format secara bersama-sama
- Diátaxis membagi kebutuhan pengguna menjadi 4 kategori, lalu memasangkannya dengan jenis dokumen tutorials, how-to guides, technical reference, explanation
- Ini bukan sekadar tabel klasifikasi, melainkan lebih dekat ke kerangka perancangan dokumentasi yang membahas apa yang harus ditulis, bagaimana menulisnya, dan di mana menempatkannya
- Pendekatan ini juga memudahkan penulis dan pemelihara untuk menilai kualitas dokumentasi, dengan keunggulan berupa sifatnya yang ringan, intuitif, dan tidak memaksakan cara implementasi tertentu
- Seperti pada kasus Vonage, Gatsby, dan Cloudflare, ini dapat digunakan sebagai acuan praktis bagi tim yang ingin meningkatkan kemudahan penelusuran dokumentasi dan struktur informasi
4 jenis dokumentasi menurut Diátaxis
- Diátaxis adalah cara berpikir sekaligus cara menjalankan penulisan dan pengelolaan dokumentasi teknis
- Titik berangkatnya adalah memahami kebutuhan pengguna dokumentasi, lalu dari sana menurunkan prinsip untuk konten, arsitektur, dan format
- Kebutuhan dan format dokumentasi dibagi menjadi 4 jenis
-
tutorials
-
how-to guides
-
technical reference
- explanation
- Dokumentasi itu sendiri juga harus diorganisasi dengan berpusat pada 4 kebutuhan ini, dan Diátaxis menangani tiga pertanyaan sekaligus
- content: apa yang harus ditulis
- style: bagaimana menulisnya
- architecture: bagaimana mengorganisasikannya
-
Penerapan untuk penulis dan pemelihara
- Diátaxis adalah pendekatan yang membantu bukan hanya pengguna dokumentasi, tetapi juga penulis dan pemelihara dokumentasi
- ringan dan mudah dipahami
- intuitif untuk diterapkan
- tidak memaksakan batasan implementasi
- memberikan prinsip kualitas yang memungkinkan pemelihara menilai pekerjaan mereka sendiri
- Prinsip-prinsip ini dirangkum sebagai sesuatu yang telah berhasil diadopsi dalam ratusan proyek dokumentasi
Contoh proyek dokumentasi nyata
- Greg Frileux dari Vonage menilai bahwa dengan Diátaxis, mereka dapat membangun kumpulan dokumentasi internal yang disukai pengguna dan mudah ditambahi oleh kontributor
- Gatsby menyatakan bahwa saat menata ulang dokumentasi open source mereka, kerangka Diátaxis digunakan sebagai sumber daya utama, dan 4 area tersebut membantu memprioritaskan tujuan pengguna untuk tiap jenis dokumentasi
- Cloudflare menjadikan Diátaxis sebagai acuan arsitektur informasi dalam desain ulang Cloudflare developer docs, dan merujuk pada kerangka ini saat menentukan di mana konten baru harus ditempatkan
1 komentar
Komentar Hacker News
Bahkan dari sudut pandang seseorang yang tidak menulis secara profesional, terlepas dari detailnya, wawasan terpenting dan paling mendasar yang saya dapat dari sini adalah tidak semua hal harus dikatakan tepat satu kali.
Sebelum menemukan gagasan ini, saya membuat diri saya sendiri kebingungan karena menganggap satu alur teks harus berperan sebagai “seluruh dokumentasi”.
Menyadari bahwa boleh menulis informasi yang sama dengan cara berbeda untuk pembaca yang berbeda saja sudah sangat membantu.
Karena pembaca akan mencari penyebut yang sama di antara contoh-contoh itu, hasilnya menjadi kurang ambigu dibanding menjelaskannya hanya dengan satu contoh.
Penulis seperti Salomo dalam Amsal di Alkitab juga banyak menggunakan teknik semacam ini.
Di abstrak, tulis “makalah ini mengevaluasi Y terhadap Z dan menunjukkan bahwa X berlaku”; di pendahuluan, jelaskan bahwa masalah A penting karena B, tetapi aspek X diabaikan, dan bahwa mengevaluasi Y mengungkap tantangan dunia nyata yang berbeda dari Z; lalu rangkum lagi, “singkatnya, karena X, Y lebih baik daripada Z”.
Dalam karya terkait pun, lanjutkan dengan mengatakan pendekatan Z memperbaiki sesuatu tetapi, seperti akan ditunjukkan nanti, belum cukup; di setiap bagian, pesan inti terus diputar kembali dan dibahas ulang.
Dua minggu lalu saya menerapkan framework ini pada dokumentasi Sequin, dan keberadaan sebuah kerangka saja sudah sangat bagus.
Sekarang alur dokumentasinya jauh lebih baik, dan karena kami tahu apa harus diletakkan di mana, menambah dan memelihara dokumentasi juga jadi lebih mudah.
Namun ironisnya, dokumentasi Diátaxis sendiri agak sulit dan bertele-tele, jadi saya baru mulai paham setelah membacanya beberapa kali.
Saat menjelaskannya ke tim, saya memakai analogi membeli alat masak seperti pressure cooker: pertama lihat quickstart (tutorial) untuk gambaran kasar bagaimana beralih dari A ke B; lalu mencari cara membuat hidangan tertentu yang disukai, itu adalah how-to; ketika muncul detail yang ingin diketahui, cek waktu memasak yang tepat untuk tiap jenis kacang di referensi; dan ketika ingin tahu mengapa tekanan mengubah waktu memasak atau bagaimana mekanisme pengamannya bekerja, barulah membaca materi penjelasan.
Lucunya, dokumentasi kami benar-benar terbalik, dimulai dengan penjelasan seperti “How Sequin Works”.
Dorongan alami engineer adalah terlebih dahulu menjelaskan cara kerja dan mengapa sesuatu dibuat seperti itu untuk menanamkan mental model, tetapi orang tidak punya waktu dan kesabaran untuk itu.
Lebih baik membiasakan mereka dengan dunianya melalui alur quickstart → how-to → referensi, lalu setelah benar-benar mendapatkan minat mereka, meyakinkan mereka tentang pendekatannya lewat materi penjelasan.
https://sequinstream.com/docs
Dokumentasi sering menjadi kabur dengan omong kosong seperti “pengalaman sinergi inovatif”, seolah perusahaan malu mengakui bahwa alatnya memang sekadar alat; atau sebaliknya, masuk terlalu spesifik sebelum membahas “mengapa produk ini ada”.
Namun CDC muncul berulang kali di dokumentasi, dan saya harus mencari definisinya. Saya pernah mengimplementasikan CDC beberapa kali dalam karier, tetapi tidak familier dengan akronimnya.
Pada akhirnya alur adalah pilihan pembaca; kepala saya bekerja dengan cara menginginkan penjelasan menyeluruh terlebih dahulu, lalu mencari how-to dan tutorial.
Dari sudut pandang penulis dokumentasi teknis, Diátaxis mirip dengan DITA: https://www.oxygenxml.com/dita/1.3/specs/archSpec/base/information-typing.html
Namun sistem seperti ini bisa melewatkan apa yang benar-benar dibutuhkan pengguna.
Jika dokumentasi teknis hanya dipakai di dalam platform dokumentasi, Diátaxis bisa cocok untuk waktu lama; tetapi jika informasi yang sama bisa, dan seharusnya, dipakai di berbagai tempat seperti UI, portal dokumentasi, dan aplikasi mobile, informasi mungkin perlu dipecah menjadi potongan-potongan yang lebih kecil dan dirakit dengan berbagai cara.
Ini disebut content reuse, yaitu cara menggunakan konten yang sama di beberapa lokasi.
Salah satu pendekatan penulisan dan penyuntingan informasi untuk content reuse dijelaskan dalam konsep “every page is page one”: https://everypageispageone.com/the-book/
Jika ada sumber daya dan waktu, saya menyarankan UX research pada tahap awal proyek. Dengan begitu, nanti Anda bisa menghindari situasi menyesakkan akibat model informasi yang terlalu membatasi.
Nielsen/Norman juga banyak meneliti area ini, dan menawarkan usulan menarik untuk menyelesaikan masalah terkait: https://www.nngroup.com/articles/information-foraging/#toc-what-is-information-foraging-2
DITA membedakan tipe topik seperti task, reference, dan concept, tetapi tutorial atau solution guide adalah kombinasi dari tipe-tipe topik semacam itu.
Di sini tampaknya fokusnya pada keluaran yang lebih besar daripada topik individual.
Saya juga penasaran apakah karena sudah sangat mendalami DITA, kompleksitasnya tidak menjadi masalah.
Jika konten dipecah menjadi potongan-potongan yang dapat digunakan ulang dan ditandai dengan semantik DITA atau DocBook, sepertinya large language model akan jauh lebih mudah “memahaminya”, tetapi saya belum pernah melihat data terkait.
Sekarang ada cara yang lebih baik untuk menulis dokumentasi daripada bergulat dengan XSL/FO dan kerabat-kerabatnya.
Di bidang penulisan dokumentasi teknis, pendekatan ini sudah sangat populer dan cukup mendekati standar
Namun, kadang ini didorong terlalu jauh sehingga halaman dokumentasi secara harfiah hanya berisi empat kategori ini, dan biasanya itu tidak berjalan dengan baik
Ini terutama berguna untuk membantu penulis mempertahankan pola pikir seperti “ini panduan, jadi jangan mencoba mengajar; fokuslah membantu pengguna mencapai hasil”
Dalam praktiknya, batas yang terlalu kaku tidak ideal, dan tidak masalah jika ada sedikit tutorial di dalam sebuah panduan
Menurut saya, titik ketika pendekatan ini mulai macet adalah saat koneksi antarkuadran kurang
Misalnya, dalam dokumentasi sebuah framework perangkat lunak, jika panduan tidak menautkan ke referensi untuk kelas atau metode tertentu yang pada akhirnya harus digunakan, akan jauh lebih sulit menelusuri konteks di sekitarnya
Beberapa dokumentasi framework konkret membagi kuadran seperti ini, dan salah satu hal paling menjengkelkan dari dokumentasi tersebut persis ini
Jika tidak ada pakar lain, bagi pemula mungkin lebih baik mengikuti aturan dengan ketat daripada “mencoba melakukan hal yang benar dengan sendirinya”
Menurut definisi, pemula tidak punya keahlian untuk membuat penilaian itu, dan seiring bertambahnya pengalaman mereka mulai melihat titik-titik di mana perlu menyimpang dari aturan baku
Mirip perbedaan antara memasak di rumah dengan mengikuti buku resep dan seorang chef profesional yang melemparkan bahan ke panci berdasarkan intuisi dan rasa
Namun saya pernah bekerja dengan orang yang bersikeras bahwa tutorial bahkan tidak boleh memiliki satu kalimat penjelasan pun, dan aturan harus diikuti secara harfiah
Di situlah letak bahaya sistem seperti ini
Ini mirip prinsip pemrograman seperti “jangan mengubah variabel global” atau “tulislah fungsi yang pendek”
Tidak perlu sepenuhnya sempurna, tetapi kebanyakan orang lebih baik bergerak ke arah itu daripada ke arah sebaliknya
Jadi saya meminta Claude mengklasifikasikan bagian teratasnya menurut Diátaxis, dan jawabannya adalah bahwa bagian itu terutama berupa penjelasan dengan beberapa unsur referensi, serta tidak ideal menurut standar Diátaxis
Katanya, lebih baik memisahkannya menjadi satu bagian yang murni menjelaskan konsep dan pentingnya penyetelan hyperparameter, serta bagian referensi terpisah yang mencantumkan alat dan metode yang tersedia
Namun setelah itu, ia juga merangkum mengapa pendekatan terpadu ini bekerja dengan baik dalam konteks panduan pengguna: mengikuti alur belajar orang dalam praktik, langsung menghubungkan konsep dengan implementasi, mengungkapkan secara bertahap dari konsep dasar ke alat yang kompleks, dan memberi nilai praktis dengan menjembatani teori dan praktik
Sebagai orang yang baru saja selesai merilis aplikasi SwiftUI pertama, saya sangat merasakan bahwa dokumentasi diperlakukan terlalu asal-asalan di industri teknologi modern
Saya sangat merindukan karya para penulis dokumentasi teknis hebat yang di-PHK Apple, dan para engineer Apple benar-benar buruk dalam menulis dokumentasi
Namun saya selalu berhati-hati terhadap pendekatan yang “dogmatis”. Mudah sekali muncul “kelas pendeta” yang tidak mau melunak meski realitas menuntutnya
Orang-orang yang pertama kali menciptakan doktrin itu bisa memanfaatkannya dengan sangat baik, tetapi para “pendeta” yang datang setelahnya bisa merusaknya dan mengubah pendekatan itu menjadi kutukan
Banyak ide bagus hancur karena penerapan yang terlalu kaku. Lihat saja “Agile” telah menjadi apa
Dokumentasi pada dasarnya memiliki dua wajah: maintainer dan pengguna, dan keduanya memiliki kebutuhan yang sangat berbeda, sehingga mungkin harus ditangani oleh tim yang benar-benar berbeda
Memang ada masalah dokumentasi di berbagai tempat bisa keluar dari sinkronisasi, tetapi yang penting adalah hasilnya
Jika beberapa instance bisa disinkronkan secara efektif, dokumentasi akan efektif dan berguna bagi konsumennya
Dokumentasi yang diformat dan disinkronkan dengan sempurna pun tidak bernilai jika tidak ada yang membacanya
The Anal-Retentive Chef yang diperankan Phil Hartman di SNL menghabiskan terlalu banyak waktu untuk persiapan sampai tidak sempat benar-benar mendemonstrasikan masakan, dan saya sering melihat hal seperti itu di bidang teknologi
Toolchain dan library bisa saja sempurna, tetapi dalam praktiknya tidak bisa digunakan
Dokumentasi adalah campuran dari berbagai bidang seperti sifat dan psikologi manusia, desain grafis, arsitektur informasi, infrastruktur teknis, serta penerbitan dan distribusi
Di sebagian besar proyek, dokumentasi diperlakukan seperti urusan belakangan, tetapi menurut saya sejak tahap requirements ia harus menjadi pertimbangan kelas satu
Tidak ada habisnya jika ingin menggali struktur dokumentasi sampai sedalam apa pun, tetapi sampai Anda menemukan titik bocornya, ia berfungsi sangat baik sebagai roda bantu
Itu terdengar seolah kesalahpahaman umum atau penerapan keliru atas sebuah ide bagus merusak ide itu sendiri
Justru ada pengalaman yang bisa diperoleh dari penerapan nyata. Jika ide awalnya ternyata memang tidak bagus, itu memecahkan ilusi; dan contoh buruk, jika disalahartikan, mengungkap ambiguitas yang dapat berujung pada kegagalan sehingga membuat ide itu lebih presisi
Namun jika banyak orang terbiasa dengan implementasi yang buruk, popularitas ide tersebut bisa turun dan permintaan terhadap implementasi yang matang juga bisa berkurang
Ini lebih mirip tragedi anti-commons daripada kemunduran ide itu sendiri
Diátaxis sangat bagus untuk menstrukturkan dokumentasi, tetapi nilai sebenarnya ada pada penyederhanaan cara menulis dokumentasi
Ia membantu kita lepas dari gagasan untuk memasukkan semuanya ke dalam satu “dokumen sempurna”, dan menyadari bahwa setiap pengguna punya kebutuhan berbeda
Tutorial adalah untuk belajar dengan mengikuti langkah-langkah, panduan adalah untuk memecahkan masalah tertentu, referensi adalah untuk pencarian cepat, dan penjelasan adalah untuk menggali “mengapa”
Kejelasan ini saja sudah bisa membuat kita menulis dokumentasi yang berguna
Namun sistem apa pun akan menjadi jebakan jika dipegang terlalu ketat
Atau saya penasaran apakah memang ada paradigma yang terpadu
Di organisasi kami, kami memakai cara ini, dan sejak mengadopsinya dokumentasi teknis kami naik ke level yang benar-benar berbeda
Ditambah dengan kepemilikan halaman dan tinjauan berkala oleh masing-masing pemilik halaman, ini menjadi satu-satunya upaya dokumentasi teknis sukses yang pernah saya lihat
Menurut saya diagram yang dipakai divio jauh lebih intuitif: https://docs.divio.com/documentation-system/
Namun tampaknya pihak Diátaxis mendokumentasikan tiap makna dengan lebih menyeluruh
Versi penulisan ulang Divio di Diataxis.fr grafiknya tidak terlalu berantakan, tetapi pada dasarnya menurut saya sama dengan yang dipakai Divio
Sejauh menyangkut ide yang disajikan dalam konteks situs web masing-masing, saya selama ini menganggap kedua materi itu praktis sebagai dokumen yang sama
Saya ingin tahu bagian mana yang terasa lebih intuitif
Saya suka ide ini, dan cukup beruntung pernah beberapa kali bertemu pembuatnya di PyConUK. Ia orang yang berbakat dan sangat ramah
Namun saya agak ragu dengan pemisahan berbagai area dokumentasi secara seketat ini
Di suatu sprint, saya pernah diberi tahu bahwa dokumen yang sedang saya siapkan tidak bisa diterima karena mencampur beberapa format. Sebagai catatan, bukan Daniele yang mengatakan itu
Bukan bermaksud berlindung di balik otoritas, tetapi saya sudah bekerja sebagai pengajar selama lebih dari 20 tahun, dan saya merasa punya cukup intuisi tentang cara menjelaskan serta memberi scaffolding pembelajaran agar orang bisa menyelesaikan pekerjaan sekaligus membangun pemahaman
Selama tidak ada kekakuan total, ini adalah alat yang sangat baik untuk memutuskan bagaimana membuat dokumentasi dan apa yang harus dilakukan oleh tiap jenis dokumen
Dalam contoh dokumentasi, misalnya di numpy, saya sering melihat kasus ketika contoh bisa dipilih jauh lebih baik daripada contoh yang terasa seperti “sihir yang jatuh dari langit”
Satu contoh yang dipilih dengan baik dapat menunjukkan cara penggunaan sekaligus memberi banyak pembelajaran tentang corner case atau hal-hal yang perlu diperhatikan
Secara teori saya rasa benar, tetapi sulit bagi saya untuk setuju. Kata-katanya terlalu mirip
Bagi saya, “tutorial”, “panduan how-to”, dan “penjelasan” secara praktis terasa hampir seperti sinonim
Kalau dipikirkan dalam-dalam, saya paham tiap kategori punya alasan yang sah, tetapi secara semantik terlalu berdekatan sehingga otak saya tidak melihat perbedaannya
Saat saya ingin tahu bagaimana sesuatu bekerja dan melihat “tutorial” serta “panduan how-to”, saya tidak tahu harus mengeklik yang mana dan akhirnya hanya mengeklik yang pertama
Mencari istilah yang lebih cocok untuk diri sendiri juga bisa menjadi latihan yang berguna
Atau bisa juga dipahami lewat pembedaan tindakan/kognisi, yaitu “melakukan vs berpikir”, serta akuisisi/aplikasi, yaitu “sedang belajar vs sedang bekerja”
Ada juga halaman khusus yang membedakan tutorial dan panduan how-to: https://diataxis.fr/tutorials-how-to/
Salah satu pembedaan paling sederhana adalah bahwa tutorial adalah sesuatu yang tidak bisa dilakukan di Stack Overflow
Tutorial mengikuti rencana pelajaran yang ditentukan pengajar, dan mengisi bagian-bagian yang bahkan tidak diketahui siswa bahwa mereka belum tahu
Di Stack Overflow, Anda harus mengajukan pertanyaan, tetapi tutorial adalah materi untuk orang yang bahkan belum tahu apa yang harus ditanyakan
Ada banyak pertanyaan populer tentang cara melakukan tugas sederhana, tetapi agar sesuai dengan format itu, Anda harus mengajukan pertanyaan, bukan meminta bantuan secara samar: https://meta.stackoverflow.com/questions/284236
Dokumen Diátaxis menjelaskan perbedaannya dengan cukup efisien: tutorial adalah pengalaman yang berorientasi pembelajaran, panduan how-to adalah instruksi yang berorientasi tujuan, referensi adalah deskripsi teknis yang berorientasi informasi, dan penjelasan adalah diskusi yang berorientasi pemahaman
“Tutorial” dalam sistem ini sebaiknya dibaca sebagai istilah teknis, bukan bahasa sehari-hari
Mirip seperti ketika psikolog mengatakan “depression”, yang tidak persis sama dengan makna sehari-harinya
Tetap saja, itu lebih baik daripada menamainya tutorial Tipe I-IV
Kuliah adalah penjelasan, sementara tutorial atau praktik adalah pengalaman terpandu, dan saya jadi teringat perusahaan fiktif Microsoft, Contoso
Panduan how-to adalah yang Anda perlukan saat mencari solusi atau bertanya ke ChatGPT, sedangkan referensi adalah seperti tesaurus, ensiklopedia, atau manual penggunaan
Video game punya tutorial bawaan, tetapi untuk puzzle yang sulit tetap dibutuhkan walkthrough, dan pengaturan tombol dicek di referensi