VuePress: Dokumentasi Menjadi Mudah
Diterbitkan: 2022-03-10Ketika datang ke setiap proyek yang memerlukan interaksi pengguna (misalnya, pengguna akhir, pengelola, dll), ada satu faktor penting yang membuat perbedaan antara keberhasilan dan kegagalan: dokumentasi yang baik. Ini berlaku terlepas dari seberapa kecil atau besar proyek Anda. Lagi pula, selain memberikan dukungan satu-satu untuk proyek Anda, dokumentasi adalah garis pertahanan pertama bagi pengguna yang mencoba memecahkan masalah. Dan suka atau tidak suka, Anda tidak akan pernah mendengar dari pengguna yang menyerah setelah tidak dapat menyelesaikan masalah mereka karena dokumentasi yang tidak memadai.
Tantangan Membuat Dokumentasi yang Baik
Dalam hal menulis dokumentasi yang baik, ada empat masalah berulang yang sering dihadapi tim:
- Dokumentasi sering ketinggalan zaman.
Meskipun tidak ada dokumentasi untuk sebuah proyek yang bisa menjadi pengalaman yang membuat frustrasi, bisa dibilang lebih buruk memiliki dokumentasi yang sudah ketinggalan zaman . Lagi pula, tujuan memiliki dokumentasi adalah untuk memberi pengguna pengetahuan resmi yang dapat mereka andalkan. Ketika kedaluwarsa, pengguna membuang-buang waktu dan akhirnya kehilangan kepercayaan pada produk Anda.
Alasan utama dokumentasi menjadi usang adalah karena pemeliharaan dokumentasi terpisah dari perubahan kode . Tanpa menginvestasikan waktu dan energi yang signifikan, ini bisa sulit untuk diselesaikan karena:- Dokumentasi biasanya ada di layanan pihak ketiga seperti Confluence atau Wiki,
- Pengembang biasanya lebih tertarik menulis kode daripada dokumentasi.
- Pengguna tidak dapat dengan mudah memberikan umpan balik.
Tidak peduli seberapa bagus menurut Anda dokumentasi Anda, pada akhirnya tidak ada artinya tanpa mengujinya dengan pengguna nyata yang dapat memberikan umpan balik. Seperti disebutkan sebelumnya, bias umum ketika mengevaluasi keefektifan hal-hal seperti dokumentasi adalah gagal memperhitungkan pengguna yang tidak dapat memecahkan masalah mereka dan menyerah. Karena tidak ada tim yang dapat menjelaskan setiap skenario tentang bagaimana pengguna dapat menggunakan produk Anda, pengguna harus memiliki cara yang mudah dan andal untuk memberikan umpan balik. - Dokumentasi sering ditulis oleh power user untuk power user.
Kelemahan dengan menggunakan alat standar seperti wiki atau file README adalah bahwa mereka sering hanya melayani sekelompok pengguna tertentu yang sering memiliki pengetahuan yang sudah ada sebelumnya tentang perpustakaan dan/atau tumpukan teknologi. Akibatnya, cukup mudah bagi mereka untuk menavigasi ruang dan menemukan apa yang mereka butuhkan. Namun, pengguna baru tidak memiliki pengetahuan sebelumnya dan seringkali membutuhkan pengalaman yang jauh lebih mendalam untuk melibatkan mereka.
Contohnya meliputi:- Situs web yang dirancang dengan baik,
- Kemampuan pencarian,
- Navigasi samping yang dipandu,
- Informasi meta yang mudah diidentifikasi (yaitu, tanggal terakhir diperbarui),
- Konten imersif yang melampaui dinding teks yang sulit dipahami dengan mudah.
- Infrastruktur yang buruk membuat dokumentasi sulit untuk dipelihara.
Seolah-olah menulis dokumentasi yang baik yang dapat dipahami pengguna tidak cukup sulit, kemudahan di mana pengembang dapat menulis dan/atau memelihara dokumentasi sangat penting untuk kelangsungan jangka panjangnya. Jadi, untuk setiap hambatan tambahan yang harus dihadapi pengembang untuk menulis dan/atau memelihara dokumentasi, semakin besar kemungkinan itu pada akhirnya akan gagal. Oleh karena itu, pengalaman penulisan dan pemeliharaan dokumentasi apa pun harus semulus dan semenarik mungkin.
Andai saja ada alat yang bisa melakukan semua ini untuk kita…
Masuk ke VuePress
Saat pertama kali mendengar VuePress, orang mungkin tergoda untuk menebak bahwa itu adalah penggabungan dari Vue.js dan WordPress. Sebaliknya, Anda harus memikirkan VuePress sebagai:
Vue.js + Mesin Cetak
Karena ketika semua telah dikatakan dan dilakukan, VuePress adalah generator situs statis!
Beberapa dari Anda mungkin berpikir, “Tunggu. Generator situs statis lainnya? Apa masalahnya?"
Meskipun ada sejumlah alat yang merupakan generator situs statis, VuePress menonjol di antara paket karena satu alasan: arahan utamanya adalah untuk memudahkan pengembang membuat dan memelihara dokumentasi yang bagus untuk proyek mereka.
Mengapa VuePress Sangat Kuat Untuk Membuat Dokumentasi?
Jawabannya sederhana. Itu dirancang dengan satu tujuan dalam pikiran: untuk membantu pengembang membuat situs dokumentasi yang hebat sambil mempertahankan pengalaman penulisan yang menyenangkan. Ini berarti bahwa ia menyediakan kerangka kerja bagi pengembang untuk:
- Buat situs dokumentasi yang indah,
- Hadir dengan fitur bawaan yang penting untuk semua situs dokumentasi,
- Optimalkan pengalaman pembuatan untuk membuatnya sesederhana memperbarui file penurunan harga.
VuePress Dapat Berdampingan Dengan Basis Kode Anda yang Ada
Ini adalah salah satu alasan utama mengapa saya sangat merekomendasikannya. Dalam hal memelihara dokumentasi, salah satu cara untuk menjaminnya akan kedaluwarsa adalah dengan mempersulit pengembang untuk memperbarui dokumen saat menulis kode. Jika Anda mempersulit pengalaman penulisan dengan memaksa pengembang memperbarui hal-hal di dua tempat yang berbeda, ini akan menyebabkan banyak gesekan dan sering kali mengakibatkan dokumentasi terbengkalai. Ini biasanya terlihat ketika pengembang harus memelihara alat pihak ketiga seperti wiki, selain basis kode itu sendiri.
Karena ini adalah generator situs statis, ini berarti ia dapat hidup dalam repo yang sama persis dengan kode Anda.
Seperti yang dapat Anda lihat dalam contoh struktur aplikasi web ini, kode Anda akan berada di direktori src
seperti biasa, tetapi Anda cukup memiliki direktori docs
untuk memuat semua dokumentasi Anda. Ini berarti Anda mendapatkan manfaat dari:
- Semua dokumentasi sekarang dikontrol versi;
- Permintaan tarik sekarang dapat berisi dokumentasi dan perubahan kode;
- Membuat skrip terpisah untuk menjalankan instance lokal dari kode dan dokumen Anda secara bersamaan;
- Gunakan pipeline build untuk menentukan apakah penerapan situs dokumentasi baru sinkron dengan penerapan kode atau tidak.
Tema Default Dilengkapi Dengan Konfigurasi Standar
Menulis dokumentasi cukup sulit, jadi VuePress melepaskan banyak keputusan yang biasanya harus dibuat dan memiliki banyak bawaan bawaan untuk membuat pengalaman penulisan Anda menjadi mudah:
- Menulis konten dilakukan terutama dengan penurunan harga.
Ini berarti Anda dapat memanfaatkan pengetahuan Anda tentang sintaks Markdown untuk menata dan memformat teks Anda.
- Penyorotan sintaks kode.
Jika Anda membangun situs sendiri, Anda harus bergulat dengan pustaka penyorotan sintaksis warna. Tetapi Anda beruntung karena Anda dapat menambahkan blok kode di VuePress dengan sangat mudah karena semuanya sudah siap untuk digunakan tanpa konfigurasi nol.
- Hal utama untuk menentukan data meta tingkat halaman.
Meskipun Anda menulis dalam file penurunan harga, Anda dapat menggunakan materi depan (seperti YAML, JSON, atau TOML) untuk menentukan metadata untuk halaman Anda agar lebih mudah untuk mengelola konten Anda!
--- title: Document Like a Pro lang: en-US description: Advice for best practices tags: - documentation - best practices ---
- Wadah penurunan harga khusus.
Jika Anda tidak tahu, Markdown memiliki ekstensi untuk menambahkan pintasan yang lebih berguna untuk membuat komponen UI yang indah seperti wadah khusus. Dan karena sangat berguna dalam dokumentasi, VuePress telah mengonfigurasinya sehingga Anda dapat langsung menggunakannya:
Fungsi Pencarian Bawaan
Mari kita hadapi itu. Tidak peduli berapa banyak waktu yang kita habiskan untuk menulis dokumentasi yang bagus, pada akhirnya akan menjadi sia-sia jika pengguna tidak dapat menemukannya. Secara umum ada dua pendekatan untuk ini:
- Tunggu robot mesin pencari merayapi situs Anda secara perlahan dengan harapan suatu hari pengguna Anda dapat menemukan halaman yang tepat di situs Anda. Bukan solusi yang bagus.
- Bangun fungsionalitas pencarian Anda sendiri, tetapi ini bisa sulit diterapkan untuk situs statis karena tidak ada kode sisi server yang berjalan untuk membuat indeks pencarian dan melakukan pencarian. Belum lagi ini mengambil waktu pengembangan jauh dari produk itu sendiri. Jadi ini juga tidak bagus.
Beruntung bagi kami, VuePress hadir untuk menyelamatkan hari sekali lagi!
VuePress hadir dengan fungsi pencarian bawaan yang menghasilkan "mesin pencari" sendiri — Anda membacanya dengan benar. Tanpa pengaturan atau konfigurasi basis data tambahan, VuePress diatur untuk mengikis seluruh dokumen Anda untuk menghasilkan mesin pencari sederhana yang akan menampilkan semua h1 dan h2 Anda kepada pengguna Anda.
Sekarang, beberapa dari Anda mungkin berpikir,
“Bagaimana jika saya menginginkan sesuatu yang akan memberikan pengindeksan tingkat rendah untuk pencarian?”
Nah, VuePress telah membantu Anda di sana juga karena dirancang untuk berintegrasi dengan mudah dengan Algolia DocSearch yang dapat menyediakan fungsionalitas itu untuk Anda secara gratis jika Anda memenuhi persyaratan mereka:
Navigasi Sidebar Sesederhana Mengaktifkan atau Menonaktifkan Fitur
Bagi siapa saja yang pernah bertanggung jawab untuk mengelola konten, Anda tahu betapa rumitnya membangun bilah sisi yang memiliki item bersarang dan kemudian melacak posisi pembaca saat menggulir ke bawah. Jadi, mengapa menghabiskan waktu untuk itu ketika Anda bisa menulis dokumen yang lebih baik? Dengan VuePress, bilah sisi semudah beralih di bagian depan halaman:
Pembuatan Otomatis Meta-Data Penting Yang Biasanya Diabaikan
Salah satu hal yang paling membuat frustrasi yang dapat ditemui pengguna adalah dokumentasi yang kedaluwarsa. Ketika pengguna mengikuti langkah-langkah dan kesulitan memahami mengapa sesuatu tidak berfungsi, dapat dengan mudah mengetahui tanggal pembaruan terakhir dapat sangat berguna bagi pengguna dan pengelola proyek.
Dengan konfigurasi sederhana, VuePress dapat memastikan secara otomatis menampilkan tanggal pembaruan terakhir pada halaman sehingga pengguna Anda selalu tahu kapan terakhir kali diperbarui.
Selain itu, dengan sedikit konfigurasi, VuePress juga sangat memudahkan pengguna untuk berkontribusi pada dokumen Anda dengan secara otomatis membuat tautan di bagian bawah setiap halaman yang memungkinkan pengguna membuat permintaan tarik ke dokumen Anda dengan mudah.
Tidak ada yang lebih mudah dari itu bagi pengguna Anda.
Penerapan Di Semua Situs Hosting Statis
Karena VuePress adalah generator situs statis pada intinya, ini berarti Anda dapat menerapkannya di platform hosting populer apa pun seperti:
- Netlify
- Halaman GitHub
- Halaman GitLab
- Heroku
- Sekarang
Yang perlu Anda lakukan untuk membangun situs adalah menjalankan vuepress build {{ docsDir }}
dengan tempat direktori Anda berada dan Anda akan memiliki semua yang Anda butuhkan untuk menerapkannya secara langsung di web!
Catatan : Untuk panduan lebih mendalam tentang cara melakukan ini, lihat panduan penerapan resmi untuk VuePress.
Memanfaatkan Vue Di Dalam File Penurunan Harga Anda
Saya tahu saya tahu. Kita bisa menggunakan Vue.js di Markdown kita?! Ya, Anda membacanya dengan benar! Meskipun secara teknis opsional, ini mungkin salah satu aspek yang paling menarik dari VuePress karena memungkinkan Anda untuk meningkatkan konten penurunan harga seperti yang belum pernah Anda lakukan sebelumnya.
Tetapkan Data Berulang Di Satu Tempat Dan Perbarui Di Mana Saja Dengan Interpolasi
Dalam contoh di bawah ini, Anda akan melihat contoh singkat tentang bagaimana Anda dapat memanfaatkan variabel lokal (seperti yang didefinisikan di frontmatter) serta yang ditentukan secara global (seperti judul situs):
--- title: My Page Title author: Ben Hong --- # {{ $page.title }} Welcome to {{ $site.title }}! My name is {{ $page.author }} and I'll be your guide for today!
Gunakan Komponen Vue Dalam Penurunan Harga
Saya akan memberi Anda waktu untuk menenangkan diri setelah membaca ini, tetapi ya, komponen Vue langsung dengan instance Vue lengkap dapat menjadi milik Anda untuk diambil jika Anda mau! Ini akan membutuhkan sedikit lebih banyak pekerjaan untuk mengonfigurasi, tetapi ini diharapkan karena Anda membuat konten khusus yang akan berjalan di dokumentasi Anda.
Berikut adalah contoh singkat tentang seperti apa komponen Penghitung dalam file Penurunan Harga:
Ini mungkin bagian paling kuat dari kustomisasi yang tersedia untuk dokumentasi karena itu berarti Anda sekarang memiliki kebebasan untuk membuat konten kustom jauh melampaui kemampuan Markdown standar. Jadi apakah itu menyediakan demo, atau beberapa kode interaktif, idenya tidak terbatas!
Langkah selanjutnya
Jika Anda ingin menyiapkan situs dokumentasi yang indah bagi pengguna Anda untuk mempelajari cara menggunakan produk Anda, itu tidak akan jauh lebih mudah daripada VuePress. Dan meskipun mungkin mudah untuk berasumsi bahwa VuePress hanya boleh digunakan oleh proyek yang menggunakan Vue.js, ini tidak jauh dari kebenaran. Berikut adalah beberapa contoh dari berbagai jenis proyek yang memanfaatkan VuePress untuk situs dokumentasi mereka:
- CMS kerajinan
- UmiJS (yang dibangun untuk Bereaksi)
- bukaHAB
- Merak
Pada akhirnya, terlepas dari apakah Anda menggunakan VuePress atau tidak, saya harap ini telah membantu menginspirasi Anda untuk membuat dokumentasi yang lebih baik bagi pengguna Anda.
Sumber Daya Lebih Lanjut
Ada banyak hal keren yang tidak saya bahas di artikel ini (misalnya bertema, blogging, dan sebagainya), tetapi jika Anda ingin mempelajari lebih lanjut, lihat sumber berikut:
- Dokumen VuePress Resmi
- Daftar Sumber Daya Terkait VuePress yang Dikurasi
- Galeri VuePress
- VuePress Blog Boilerplate