Ngoding Dokumen Teknis

Jaman dulu sekali saya tidak pernah berpikir kalau suatu saat saya bakalan sangat peduli soal alat untuk tulis menulis. Sebenarnya, memang sudah sejak muda saya punya bakat untuk menyusahkan diri sendiri. Waktu itu, beberapa orang dosen di kampus menggalakkan pemakaian Latex untuk menyusun skripsi. Dikeluarkanlah format Latex untuk penulisan skripsi sesuai standar kampus. Di saat teman-teman yang lain kerepotan untuk mengatur MS Word bajakannya untuk bisa sesuai dengan standar universitas, saya memilih untuk repot dengan jalan yang lain. Saya ambil itu format Latex, lalu digabungkan dengan sebuah program mengetik bernama Lyx. Mengetik dengan Lyx tidak perlu tahu soal Latex. Latex dipakai untuk memformat dokumen di belakang layar sebelum dibuat menjadi PDF. Jangan ditanya betapa susahnya saya ngoprek tipe dokumen article supaya bisa jadi skripsi ala kampus saya. Ada alternatif ketiga sebenarnya. Teman-teman lain yang lebih mengarus utama memilih untuk langsung untuk menulis langsung dengan Latex. Akan tetapi, bukan saya namanya kalau gampang percaya dengan arus utama.

Setelah insiden coffee grinder HL 600N belasan tahun kemudian, keyakinan saya yang memandang rendah arus utama jadi semakin mengkristal. Bagus atau jeleknya sesuatu tidak ada hubungannya dengan banyaknya pemakainya. Salah satu contoh rancangan bagus yang dipakai banyak orang misalnya layar sentuh telepon kita. Contoh-contoh rancangan jelek yang dipakai banyak orang ada banyak sekali. Saya sampai sebal bahkan untuk sekedar menyebutkannya. Baik, sebut satu saja ya. Itu, aplikasi OJOL dari negeri tetangga. Saya sampai ingin membanting hape setiap kali memakainya. Tapi, diskonnya memang gede. Inilah mengapa yang bagus kalah dengan yang jelek. Pada akhirnya, semua kembali kepada uang.

Kembali soal tulis menulis. Sebagai seorang yang pernah mencicip posisi software architect walau tidak lama, saya mempunyai kebutuhan khusus untuk bisa menulis dokumen teknis dengan cepat. Sebagai orang yang otaknya sudah pindah ke jari, menggambar diagram-diagram arsitektur secara klak klik gesar geser dengan mouse terasa sangat lama. Ide-ide yang bebas melayang-layang di kepala seringkali menguap begitu saja sebelum sempat si tikus terpegang. Hal ini diperparah dengan kenyataan bahwa program untuk menulis dokumen seringkali berbeda dengan program untuk menggambar diagram. Saya harus pindah berkali-kali antara dua program. Jangan sebut-sebut kalau ada MS Word! Tidak masuk hitungan!

Menelaah Kebutuhan

Berdasarkan cara kerja yang jari-oriented tadi, saya menentukan beberapa acuan untuk memutuskan alat tulis dokumen teknis yang bagus:

1. Memisahkan isi dan tampilan

   Ketika berpikir dan menulis soal isi, jangan sampai kita teralihkan perhatiannya oleh tampilan. Oleh karena itu, tampilan haruslah sesuatu yang bisa diputuskan belakangan, dan dapat dengan mudah diubah tanpa harus mengacak-acak isinya.

2. Semuanya ada di satu tempat

   Baik itu diagram, potongan kode, ataupun artikelnya sendiri, semuanya harus ada di dokumen yang sama. Ini penting supaya kita tidak kehilangan aliran ide ketika sedang menulis. Begitu dapat ide suatu bentuk arsitektur tertentu, kita bisa langsung menuangkan di situ dengan cepat.

3. Berformat teks biasa

   Alasannya adalah supaya bisa dengan mudah dilacak ketika terjadi perubahan. Kalau dokumennya berformat docx atau odt misalnya, maka akan susah dilacak perbedaannya antara dokumen-dokumen terdahulu dengan yang sekarang. Format teks biasa juga ramah terhadap program version control, sehingga bisa ditaruh berdekatan dengan source code perangkat lunak yang bersangkutan. Artinya, diagram juga harus berbentuk teks. Idealnya memang harus ada kedekatan tempat dan waktu yang kuat antara dokumen dan kodenya.

4. Gampang dibaca, gampang ditulis

   Bahkan dalam bentuk mentahnya, dokumen ini harus gampang dibaca dan ditulis. Tidak semua format teks biasa gampang dibaca dan ditulis. Format teks yang susah dibaca dan ditulis misalnya HTML, XML, dan Docbook. Mau menulis hal yang sederhana saja, duh ribetnya. Catatan lagi soal diagram, membaca dan menulis diagram juga harus gampang dan cepat.

Acuan-acuan ini selain menunjukkan bahwa selain jari-oriented, saya adalah seorang yang content oriented. Maklum, enjinir biasa kayak saya kan jarang bertemu langsung dengan pelanggan. Soal tampilan nanti saja, yang penting apa yang disampaikan sudah tepat. Apalagi kalau kita dituntut untuk cepat dalam keseluruhan proses pencetusan ide hingga pewujudannya.

Jalan-jalan belanja alat

Markdown, piranti sederhana yang hampir bagus

Markdown memang cuma format dokumen biasa, tapi jika digabungkan dengan Visual Studio Code, mereka menjadi alat yang lumayan enak untuk ngoding dokumen. Kelebihan markdown adalah pada kesederhanaan formatnya yang nyaris tidak perlu dipelajari. Visual Studio Code mempunyai plugin bawaan yang langsung bisa menampilkan markdown. Di antara kekuatan markdown adalah dia bisa menampilkan potongan kode. Program pendukungnya juga banyak. Bahkan kita bisa mengekspor dokumen markdown ke format PDF. Markdown didukung penuh oleh Github. Jika kita sering berurusan dengan proyek-proyek open source dan ada dokumen markdown di dalamnya, Github akan mempercantik tampilannya.

Akan tetapi, markdown ini tidak bisa menampilkan diagram. Paling banter, dia hanya bisa menampilkan link gambar dari tempat lain. Saya harus menggambar (mengetik) di situs lain lalu menyalin link-nya ke dokumen yang sedang ditulis. Potongan kode PlantUML di bawah ini

@startuml
Bob -> Alice : hello
@enduml

harus digambar langsung di website-nya, lalu link-nya ditampilkan di sini

Kelemahan ini kemudian saya tambal dengan memakai plugin VSCode tambahan, yaitu “Markdown Preview Enhanced”. Kalau memakai Markdown Preview Enhanced, sequence diagram Bob-Alice di atas sudah langsung jadi diagram seperti di bawahnya. Akan tetapi, saya mengalami kesulitan ketika ingin membuat versi PDF-nya. Saya menyerah.

Tidak hanya itu, markdown ini punya masalah yang sangat mengesalkan. Varian dari markdown ini banyak, sehingga tiap orang bikin penampilnya sendiri-sendiri. Karena terlalu sederhana, masing-masing menambahkan markdown dengan sintaks-sintaks khusus untuk melengkapi fitur yang tidak dimiliki markdown. Akibatnya, seringkali markdown yang sudah ditulis di satu platform jadi nampak berantakan di platform yang lain. Sebagai contoh, markdown-nya Gitlab, Github, dan Bitbucket saja sudah berbeda. Faktor terakhir inilah yang membuat saya ngambek dan berhenti tidak memakai markdown lagi untuk dokumen-dokumen teknis.

Asciidoc, konsisten karena tidak ada saingannya

Banyak orang bilang, standar itu bagus. Dengan adanya standar, setiap orang bebas mengimplementasikan versinya masing-masing dan tidak dimonopoli salah satu pihak saja. Pada praktiknya, pendapat seperti ini lebih sering membuat masalah. Contohnya adalah C++ dengan standar ISO-nya. Akibat adanya standar ISO C++, muncullah undefined behavior yang tujuannya supaya masing-masing compiler bisa punya kesempatan untuk mengoptimisasi program sesuai dengan mesin di mana program dijalankan. Kenyataannya, setiap kali mendengar undefined behavior, saya selalu merasa bahwa bayaran saya harusnya empat kali lipat lebih tinggi.

Itulah yang terjadi pada markdown. Banyaknya versi yang bersliweran bukannya mempermudah pemakainya malah justru membuat repot dalam hal-hal yang nggak penting. Si penulis harus ekstra hati-hati karena dia harus memikirkan si dokumen teknis mau ditampilkan di mana. Kalau begini caranya, mana bisa memusatkan perhatian pada isinya yang jauh lebih penting?

Itulah mengapa saya melirik AsciiDoc. Walaupun dulu ada versi Python-nya, pada praktiknya yang paling banyak beredar cuma satu versi dari proyek “AsciiDoctor” saja yang berbasis Ruby. Bahkan, versi NodeJS-nya pun bersumber dari versi Ruby yang di-transpile ke Javascript, dan dikelola oleh proyek sama. Artinya apa? Menulis dengan format AsciiDoc dijamin tidak akan bermasalah di mana saja, karena yang bikin itu-itu juga orangnya.

AsciiDoc sendiri juga memiliki fitur yang jauh lebih banyak dari markdown. Yah, walaupun itu artinya harus belajar lebih banyak hal juga. Walaupun sintaksnya memang rada aneh dan kurang alamiah, demi alasan konsistensi saya kesampingkan masalah itu. Fitur-fitur seperti tabel yang canggih, adanya kotak perhatian (kalau bahasa Inggris-nya admonition), dan kemudahannya untuk diubah ke format macam-macam (odt, docx, pdf, html) membuat saya semakin mantap untuk memakai AsciiDoc.

Tentu saja, untuk bisa nyaman saya tetap memakai VSCode dan plugin resmi AsciiDoc dari AsciiDoctor. Satu plugin ini sudah mencakup semua yang saya butuhkan untuk menulis dokumen teknis. Mau menggambar diagram UML? Bisa. Mau menggambar grafik atau diagram lain? Bisa. Mau export ke HTML atau PDF? Tentu sudah pasti. Semuanya bisa dilakukan dari sebuah dokumen teks biasa saja. Ini tepat seperti yang saya mau!

reStructuredText? Apa itu?

Ketika sedang nyaman-nyamannya memakai AsciiDoc, saya menemukan bahwa ada alternatif lain untuk menulis dokumen teknis yang bernama reStructuredText. Pengguna utama format ini adalah komunitas Python dengan Sphinx sebagai alat utamanya. Kalau kita sering menemui dokumentasi proyek open source yang ditampilkan di Read the Docs, nah itu ditulisnya dengan restructuredText. Setelah saya lihat sekilas, ternyata memang sintaksnya memang terkesan lebih alamiah dan bisa untuk menggambar diagram juga. Hanya saja, tidak ada plugin yang bagus di VSCode. Itu artinya apa yang ditulis tidak bisa langsung tampil. Si Sphinx harus dijalankan terlebih dahulu barulah hasilnya bisa terlihat. Akhirnya, saya memutuskan untuk melewatkan restructuredText dan Sphinx begitu saja.

Docusaurus, kompromi antara keindahan dan fitur

Docusaurus bukanlah format dokumen teknis sebagaimana Markdown, AsciiDoc, atau reStructuredText. Dia adalah alat untuk menghasilkan halaman web yang berisi dokumen teknis. Dalam hal ini, dia malah lebih mirip seperti Hugo, Jekyll, Gatsby, atau bahkan Sphinx. Akan tetapi, sebagai sebuah solusi menyeluruh, Docusaurus adalah pilihan menggiurkan.

Docusaurus memilih format dokumen MDX yang memperkuat markdown biasa dengan sintaks-sintaks ReactJS. Jadinya, kita bisa menyisipkan komponen-komponen ReactJS ke dalam dokumen kita. Ini kekuatan utama sekaligus kelemahan MDX. Perhatian kita kepada isi akan teralihkan oleh fitur keindahan MDX. Masalahnya, ReactJS itu hanya ada artinya kalau yang menulis dokumen adalah seorang web frontend engineer. Kalau buat saya pribadi sih, buat apa?

Yang keren dari Docusaurus ini justru malah fitur kotak perhatian (admonition) dan potongan kode yang bisa dijejer-jejer dalam tab yang berbeda-beda. Sudahkah saya bilang kalau Docusarus ini indah? Bahkan, tidak diapa-apakan saja sudah indah. Menarik untuk orang malas seperti saya. Kalau kita sudah pasti tidak ingin berpindah ke lain hati, maka Docusaurus adalah pilihan yang tepat untuk mendokumentasikan produk-produk perangkat lunak kita. Hanya saja, saya tetap tidak memilihnya untuk keperluan pribadi karena alasan tidak bisa menulis diagram langsung di berkas MDX-nya.

Zola, untuk yang tidak teknis-teknis amat

Walaupun bukan pengguna setianya, saya naksir berat sama bahasa pemrograman Rust. Awal perkenalan saya dengan Zola karena dia dibuat dengan Rust. Zola ini mirip semacam Hugo KW yang bisa mengubah dokumen teks biasa jadi website yang indah. Zola mudah dipakai karena semuanya sudah tersedia dalam satu program saja dan tidak usah harus nyetting aneh-aneh (… uhuk … npm … uhuk …). Sayangnya, format dokumen yang bisa dicerna sama Zola cuma markdown. Tidak apa-apa, sudah rada mencukupi kalau kebutuhannya untuk menulis blog saja. Itulah mengapa blog saya yang ini menggunakan Zola. Tinggal push ke Github, si Netlify nanti bakalan menampilkan isi terbaru blog saya. Beres.

Hugo, jalan keluar sapu jagat

Sayangnya, pilihan tema Zola tidak banyak. Gini-gini saya juga bisa bosen sama warna yang itu-itu saja. Alasan utama saya melirik Hugo adalah karena pilihan temanya sangat banyak. Setelah diselidiki lebih lanjut, ternyata Hugo ini juga mendukung format dokumen AsciiDoc dengan AsciiDoctor. Mantap! Tidak hanya itu, Hugo juga mendukung penulisan diagram dengan asciidoctor-diagram. Walaupun sedikit berbeda dengan asciidoctor-kroki yang ada di plugin VSCode, tetap tidak masalah. Proses kreatif saya tidak terganggu.

Dengan begini, blog saya bisa dikembangkan menjadi sebuah website pribadi yang sekaligus bisa menayangkan artikel-artikel yang sangat teknis, atau bahkan bisa menulis buku sekalian. Tampilannya juga akan jadi sedikit lebih enak dilihat karena temanya bisa diganti dengan yang lebih “adem”. Ya, supaya jadi penyeimbang isinya yang pedas menggigit. Yang jelas, temanya bakalan apa adanya, tidak ada custom-customan. Ribet! Tapi, kok mau pindah rasanya males ya?

Confluence, sebuah pilihan buruk

Confluence adalah produk dari Atlassian untuk menulis dokumentasi yang memiliki konsep wiki. Setiap pengguna bebas menulis apa saja di dalamnya. Dia juga dilengkapi dengan editor WYSIWYG, yang intinya nanti menghasilkan dokumen HTML. Kelebihan utama dari Confluence adalah integrasinya dengan Bitbucket dan JIRA. Kita juga bisa membuat template aneh-aneh untuk menulis macam-macam dokumen. Kelihatannya tidak ada yang aneh, bukan?

Lalu, apa yang membuat saya membencinya? Yang paling utama tentu saja vendor lock-in. Si Confluence ini terasing dari peradaban. Untuk menampilkan dokumen markdown saja harus pakai plugin. Untuk mengimpor dokumen docx saja, sering berantakan. Sudah begitu, dia tidak ramah version control. Artinya, dokumen-dokumen Confluence bakalan jauh dari sumbernya. Sebenarnya, perubahannya bisa dilacak sih, tapi harus pakai cara dia. Ngeselin!

Artinya, Confluence ini bagi saya lebih jelek dari Zola. Zola sama-sama tidak bisa menulis diagram di dalam dokumen. Tapi, Zola lebih bagus karena ramah version control. Confluence hanya terasa manfaatnya kalau yang menggunakan itu menganggap JIRA dan PR Bitbucket sebagai hal terpenting dalam hidupnya. Saya curiga, dulu kantor saya memakai Confluence gara-gara dipaksa sama seorang Product Manager supaya dia bisa menulis laporan ala WYSIWYG di Confluence sambil mengutip tiket-tiket JIRA dan daftar PR di Bitbucket. Saya heran, apa sih enaknya Confluence? Sudah bayar, jelek lagi.

Menyesuaikan (menyiksa) diri dan meningkatkan kecerdasan

Sesampainya di bagian ini, saya jadi berpikir, “Seandainya lebih tua sepuluh tahun, mungkin saya sudah menjadi pengguna Vim garis keras”. Pengguna Vim percaya bahwa untuk meningkatkan produktivitas, seseorang perlu melatih keterampilan baru ketika menggunakan “alat yang lebih canggih”. Kalau sudah mahir (misalnya, mahir Vim), maka dia akan jauh lebih produktif daripada orang biasa yang tidak belajar apa-apa dan hanya menggunakan alat biasa saja (WYSIWYG).

Kenyataannya, saya malah menjadi pendukung fanatik Jetbrains yang produk-produknya terkenal gembul. Saya berlangganan paket personal tahunan “All Products Pack” dari Jetbrains. Prinsip saya sih cuma satu. Sebagai seorang yang kegiatan utamanya adalah berpikir, alat yang bagus adalah alat yang membantu seseorang berpikir, memusatkan pada hal-hal yang penting dan menangani hal-hal yang tidak penting. Kalau dengan belajar hal baru membuat seseorang jadi lebih cerdas sebagai seorang pemikir, maka belajar hal baru itu baik.

Begitu juga ketika menulis dokumen teknis. Hal yang paling saya pedulikan adalah flow. Bagaimana bisa menangkap ide-ide liar di dalam kepala dan menatanya ke dalam tulisan. Boleh jadi, ide liar itu adalah ide yang berharga milyaran rupiah. Untuk itulah, berkorban sebentar dengan belajar sintaks AsciiDoc dan PlantUML menjadi hal yang terasa ringan.

Belajar AsciiDoc

Satu hal yang menurut saya perlu penyesuaian ketika belajar AsciiDoc adalah sintaks untuk membuat daftar bersarang, macam begini nih:

1. Nomer
   a. Huruf
   • bulatan
   • bulatan lagi
   • bulatan yang ketiga

karena antara sintaks dan tampilan sangat berbeda:

. Nomer
.. Huruf
*** bulatan
*** bulatan lagi
*** bulatan yang ketiga

Hal lain lagi misalnya soal tabel yang sangat canggih karena bisa diatur perbandingan lebarnya dan bisa dibuat rata kiri, rata kanan, rata atas, rata bawah, bahkan bisa dibuat tabel di dalam tabel. Bisa juga menggabungkan baris atau kolom. Kadangkala, saya harus sering-sering melihat manualnya. Tidak apa-apa, lama-lama juga hafal.

Yang saya masih sering bingung adalah macam-macam blok di AsciiDoc. Blok di AsciiDoc artinya bisa lain-lain, bisa untuk kotak perhatian / admonition, bisa untuk source code, bisa untuk ditampilkan apa adanya, bisa juga berarti kutipan.

Caranya menulis juga bisa lebih dari satu. Kalau tidak diselingi baris kosong, maka bisa seperti dibawah ini:

[listing]
npm install -g asciidoctor

[quote]
Ucapan Orang terkenal

[CAUTION]
Ini harus diperhatikan!

Sementara kalau ada baris kosong, lebih enak ditulis seperti di bawah ini:

[source, lua]
----
function dosomething()
    print('do something')
end
----

[quote, Wijaya]
____
Ternyata quote itu pembatasnya garis bawah, bukan tanda sambung
____

[CAUTION]
====
Awas, AsciiDoc susah!
====

[plantuml]
....
@startuml
title Diagram pembatasnya bisa dengan titik
Alice -> Bob
@enduml
....

....
$ echo Titik aslinya menampilkan teks dalam bentuk font berlebar tetap
....

Begitu sudah hafal macam-macam pembatas blok di atas, rasanya sudah lega. Karena 80% kebutuhan sintaks AsciiDoc sudah terpenuhi.

Belajar PlantUML

Saya tahu PlantUML sudah sejak entah kapan, pokoknya sudah lama. Ketika kawan-kawan di kantor mulai banyak yang memakai sequencediagram.org, yang terbayang langsung PlantUML. Karena itu, tidak ada alasan untuk pindah dari PlantUML yang sudah jalan baik tanpa masalah dan jelas-jelas open source. Kalau perlu, bahkan bisa dipasang sendiri di jaringan lokal.

Bayangan saya, ngoding diagram itu gampang. Kita tinggal menyatakan strukturnya, tampilnya gambar seperti apa tinggal si PlantUML ini yang ngatur. Sayangnya, tidak semudah itu. Seringkali kita harus pake trik-trik kotor seperti membuat garis tak kasat mata supaya kotak-kotanya bisa sejajar. Selain itu, kita harus paham bahwa PlantUML itu bekerja berdasarkan flow layout. Jadi, asalkan kita mengalah untuk tidak memaksa mana yang kiri duluan atau mana yang kanan duluan, yang jatahnya ada di baris yang sama tidak akan lari ke baris berikutnya. Setelah bisa mencapai saling pengertian dengan PlantUML, barulah kita bisa produktif menuangkan ide-ide kita ke dalam gambar.

Sebenarnya asciidoctor-kroki tidak hanya punya PlantUML saja. Kita kalau mau bahkan bisa menggambar grafik. Misal, mau menggambar burndown chart atau benchmark result kita bisa pakai Vega atau Vega-Lite. Ada juga yang aneh kayak Ditaa atau svgbob, tapi saya tidak suka karena bakalan merusak aliran ide saya. Bahkan, PlantUML sendiri itu sebenarnya punya banyak jenis diagram kok. Saya sering membuat mindmap dengan PlantUML, bahkan pernah beberapa kali membuat Gantt chart.

Berkompromi dengan Confluence

Nah, ini yang ngeselin. Mau bagaimana lagi, namanya kerja bareng orang, ya harus mau ikut aturan. Awalnya saya bingung bagaimana caranya mengkonversi AsciiDoc ke Confluence. Bahkan saya sempat ngoprek-oprek Pandoc demi mendapatkan format docx. Ya, karena Confluence punya plugin docx. Lumayan nyebelin karena peluang berantakannya dua kali. Ketika dikonversi jadi docx dan ketika dikonversi dari docx jadi halaman Confluence.

Ternyata, ada jalan yang lebih mudah. Di VSCode, format tampilannya berupa HTML. Si Confluence ini rupanya ramah sama HTML. Draft yang sudah jadi di halaman preview VSCode saya copy-paste langsung ke halaman Confluence. Beres!

Membuat slide presentasi

Nah, yang ini bonus. Sebelum mengenal AsciiDoc, saya memakai markdown untuk menyusun presentasi. Naskah presentasi ini kemudian harus dikonversi jadi slide HTML ala reveal.js dengan program Node yang bernama backslide. Setelah memakai AsciiDoc, ternyata si proyek AsciiDoctor ini menyediakan juga plugin untuk membuat presentasi yang bernama “AsciiDoc Slides”. Hasilnya sangat memuaskan. Saya tidak perlu lagi program tambahan. Tampilannya juga sangat cantik, seandainya saya mengerti CSS. Besok saya mau usul ah, supaya ada temen yang mau bikinin saya tema CSS berlogo kompeni.

Habis ini Apa?

Nah, sesudah perjuangan yang berliku-liku demi menemukan senjata pamungkas untuk ngoding dokumen, saatnya saya untuk … kerja lagi. Ya memangnya mau ngapain lagi? Namanya bikin dokumen teknis ya dipakai untuk kepentingan kerja, gimana sih?