Pengalaman Membuat Modul Panduan

Tahun 2010, saya pernah membuat ebook perihal Administrasi Debian Server. Ebook dibuat untuk kebutuhan pembelajaran bagi adik-adik kelas di SMK. Sesuai dengan saran dari pak Budi Sumawijaya selaku guru dan pembimbing saya ketika ada lomba LKS. Aplikasi yang digunakan untuk membuat ebook tersebut adalah OpenOffice.

Ketika join dengan Excellent, saya juga disarankan untuk membuat modul panduan oleh pak Vavai. Lebih tepatnya mengupdate modul panduan yang sudah ada. Yang dibuat oleh pak Vavai dijaman-jaman baheula. Seperti modul panduan Training Zimbra, Mastering Proxmox, Linux Active Directory dan Open Stack Fundamental. Modul-modul tersebut saat ini sudah mengalami beberapa transformasi yang dapat dibaca disini : https://imanudin.com/2018/09/13/transformasi-modul-panduan-mandiri-excellent/

Kebanyakan modul panduan/dokumentasi yang pernah saya buat, dibuat menggunakan aplikasi LibreOffice/OpenOffice. Tentu karena alasan tampilan yang menarik dan mudah digunakan. Tinggal klik dan atur.

Ketika melihat dokumentasi panduan yang dibuat oleh SUSE/openSUSE, saya tertarik juga untuk membuat panduan dengan format seperti itu. Dari sisi tampilan cukup rapi dan clean. Setelah baca isi salah satu dokumentasinya, format yang digunakan untuk membuat dokumentasi tersebut adalah format Docbook. Saya download source codenya dari Github dan digenerate dengan aplikasi DAPS yang dapat diinstall pada openSUSE.

Menggunakan format Docbook ini cukup sulit. Karena harus jeli terhadap kurangnya tanda buka ataupun tanda tutup. Jika ada yang terlewat saja, maka aplikasi DAPS tidak bisa melakukan generate. Tentu disertai dengan error. Salah satu panduan yang pernah saya buat menggunakan Docbook adalah Ebook Panduan Instalasi dan Konfigurasi SUSE OpenStack Cloud.

Suatu ketika, pak Vavai pernah share perihal membuat dokumentasi yang mudah menggunakan Markdown. Sebuah pengalaman dan tulisan yang dibuat oleh mentor beliau. Yaitu pak Endy Muhardin. Saya pun tertarik untuk membacanya dan mencobanya. Tulisan tersebut bisa dibaca disini : https://software.endy.muhardin.com/aplikasi/membuat-dokumen-dengan-markdown-dan-pandoc/ . Beliau juga memiliki source code contohnya di Github yang dapat diakses disini : https://github.com/endymuhardin/buku-pandoc

Ternyata cukup mudah menggunakan format markdown ini. Saya tidak perlu dipusingkan perihal tampilan format, Header ataupun tampilan yang lainnya. Saya cukup fokus saja pada materi atau informasi yang akan dituliskan dan biarkan format markdown mengatur tampilannya. Format markdown ini juga banyak di gunakan pada berbagai project di Github. Khususnya pada bagian README.md yang berisi informasi perihal project atau tata cara penggunaan project.

Kemudian, saya lihat dokumentasi atau panduan yang dibuat oleh Zimbra. Panduan tersebut berformat asciidoc/adoc yang disimpan pada Github. Tampilannya cukup rapi. Format penulisannya hampir sama dengan markdown. Anda bisa lihat contoh panduan yang dibuat berformat adoc disini : https://github.com/Zimbra/adminguide. Anda juga bisa generate hasil penulisan dengan format adoc menjadi PDF, HTML, EPUB dan format lainnya yang disupport dengan bantuan Asciidoctor. Bahkan jika saya lihat, bisa di convert juga menjadi format Docbook. Setelah menjadi format Docbook, saya bisa generate lagi menggunakan DAPS jika hasilnya ingin seperti Ebook panduan SUSE Cloud OpenStack 😀

Melihat kemudahan penggunaan Asciidoc seperti adanya entity dan memanggil file adoc lainnya, penggunaan format adoc mulai saya gunakan beserta team dilingkungan kerja. Format adoc kami gunakan untuk beberapa dokumentasi dan informasi aktivasi yang biasa dikirimkan pada klien. Khususnya informasi yang perubahannya tidak terlalu banyak. Dan perubahan yang sering diedit, bisa diotomatiskan menggunakan entity layaknya mail merge. Cukup ubah pada bagian tertentu saja, generate dan langsung jadi.

Ketika sedang kuliah, saya juga menggunakan format adoc untuk memudahkan membuat semacam catatan pribadi. Tentang apa yang disampaikan dan diajarkan oleh Dosen. Hasil dari catatan tersebut digenerate menjadi format PDF dan di broadcast ke group WA kelas. Beberapa contohnya bisa dilihat disini : https://github.com/imanudin11/kuliah

Jika menggunakan Visual Studio Code sebagai text editor, format penulisan adoc bisa langsung dilihat hasil previewnya. Cukup install saja extensions yang dibuat oleh Joao Pinto

Atau jika menggunakan browser Chrome, bisa install extensions Asciidoctor.js Preview.

Untuk memudahkan, saya membuat semacam template format adoc yang biasa digunakan untuk membuat panduan ataupun dokumentasi. Template tersebut saya sadur dari beberapa website. Khususnya dari http://asciidoc.org/ dan https://asciidoctor.org/. Templatenya bisa anda lihat atau download disini : https://github.com/imanudin11/kuliah/blob/master/template_buku_dokumentasi.adoc

Jika dibuka menggunakan Visual Studio Code yang sudah terinstall extensions AsciiDoc, tampilannya seperti berikut

Tentu saja template tersebut hanya sebatas catatan pribadi. Format-format penulisan Asciidoc yang biasa saya gunakan. Dari segi fungsi dan fitur, masih banyak yang bisa ditambahkan dan dipelajari. Contoh penggunaannya bisa dilihat disini : https://asciidoctor.org/docs/asciidoc-writers-guide/

Dari beberapa tools yang pernah saya pakai seperti OpenOffice/LibreOffice, Latex, Markdown, Pandoc, Docbook, DAPS dan Asciidoc untuk pembuatan dokumentasi atau panduan, menurut saya Asciidoc yang palih mudah digunakan, simple dan kaya dengan fitur. Tapi itu pendapat pribadi saya saja. Tentu anda punya pendapat yang lain bukan? atau pendapat anda sama seperti saya 🙂