MkDocs - Project Documentation with Markdown

Bismillahirrahmanirrahim.

Membuat user guide atau panduan user dari aplikasi yang kita bangun adalah pekerjaan yang lumayan menyita waktu. Apalagi bagi seorang freelancer, umumnya paduan user ini dibuat setelah project selesai, karena semua dikerjakan sendiri. Kita harus mencari cara agar mempermudah pekerjaan ini.

Salah satu tool yang bisa kita gunakan untuk membuat panduan sistem adalah MkDocs. MkDocs ini adalah sebuah static site generator yang ditujukan untuk membuat project documentation.

Beberapa klien yang meminta dibuatkan user guide, saya buatkan dengan tool MkDocs ini.

Kelebihan MkDocs

Kelebihannya yang saya ketahui antara lain :

1. Menulis dengan markdown (bagi yang terbiasa menulis readme di github, nyaman dengan ini).
2. Auto-reload on save changes (refresh otomatis saat file disimpan).
3. Top Navbar otomatis sesuai struktur folder dan file.
4. Table of content (daftar isi) otomatis mendeteksi setiap header dokumen (#, ##, ###, h1, h2, h3, h4, …).
5. Scroll spy pada table of content.
6. Fitur search dokumentasi.
7. Bisa custom CSS dan JS.
8. Mobile responsive (bootstrap 3).
9. Bisa dipublish ke github pages.

Keren ya.

Contoh Project MkDocs

Ini contoh yang dipublish dengan github pages :
https://nafiesl.github.io/panduan-penjualan.

Source codenya di github :
https://github.com/nafiesl/panduan-penjualan.

Silakan teman-teman yang mau coba :
http://www.mkdocs.org, ada panduan installasinya.

Manfaat MkDocs

Yang saya rasakan dari menggunakan MkDocs ini, dapat mempercepat pembangunan dokumentasi project, karena :

1. Bisa fokus ke konten, karena tampilan yang cantik sudah diberikan oleh MkDocs.
2. Tidak perlu tekan tombol refresh browser karena auto-reload.
3. Sudah dalam format HTML, tinggal upload ke production server/hosting.

Kendala pada MkDocs

Satu yang belum saya temukan di MkDocs adalah konversi ke file PDF, karena kadang klien juga minta versi PDF nya untuk dibaca secara offline, atau dibagi-bagi ke user yang menggunakan sistem. Jadi untuk kebutuhan ini, solusinya dengan menggunakan LibreOffice Writer.

Oke, demikian sharing singkat tentang MkDocs, mudah-mudahan bermanfaat bagi yang membutuhkannya.

Terima kasih atas waktu teman-teman sudah membaca.