Dokumentasi dengan MkDocs

Dalam mata kuliah Interaksi Manusia dan Komputer (Human Computer Interraction) ada satu bab tentang dokumentasi help. Salah satu dokumentasi penting adalah dokumentasi online yang menjelaskan suatu aplikasi yang dibuat. Kalau jaman dulu mungkin berupa berkas readme atau file pdf tata cara penggunaan. Namun saat dunia online seperti saat ini, mau tidak mau kemampuan mendokumentasi online mutlak diperlukan. Sayang kan kalau harus bayar ke orang untuk publish onlinenya. Server online pun banyak yang gratis kalo hanya untuk dokumen, misalnya yang terkenal Github.io (lihat post yg lalu).

Banyak aplikasi untuk membuat dokumentasi online misalnya document360, nuclino, Github, MarkdownPad, ProProfs, Read the Docs, Doxygen, dan lain-lain. Nah, postingan ini akan membahas MkDocs, sebuah alat membuat dokumentasi online berbasis Python.

MkDocs memiliki keunggulan, yakni cepat dan gratis. Salah satu problem utama adalah untuk yang belum pernah menggunakan Python, karena harus belajar sedikit. Kalau sudah pernah dengan mudah dapat menjalankannya. Alur untuk pembuatan dokumentasi online dengan MkDocs adalah:

  • Instal MkDocs
  • Mengunduh Template
  • Mengedit mkdocs.yml dengan editor
  • Mengedit index.md dengan editor
  • Menjalankan server lokal MkDocs
  • Mendeploy hasil edit
  • Mempublish online

Lumayan panjang, tapi tidak membutuhkan sumber daya yang besar. Semua dapat dibuka dengan cepat. Sedikit butuh kreativitas ketika mengedit mkdocs.yml dan index.md. Karena ketika kita menjalankan server MkDocs kita langsung melihat perubahannya, jadi mirip mengkustomasi wordpress misalnya.

Ada sedikit rancu bagi pengguna awal, di sini mkdocs server (dengan mengetik mkdocs serve) hanya berfungsi melihat hasil editan saja, kalau ingin publish misal di XAMPP perlu mendeploy lewat fungsi mkdocs gh-deploy yang akan menghasilkan folder yang siap diupload di folder docs.

Untuk jelasnya lihat video berikut ini. Sekian, semoga bermanfaat.