Markdown sedang menghambat Anda

• Markdown, yang banyak digunakan untuk menulis dokumentasi pengembangan, populer berkat kesederhanaan dan aksesibilitasnya, tetapi memiliki keterbatasan untuk dokumentasi teknis berskala besar karena kurangnya daya ekspresi struktural
• Markdown bekerja seperti sistem tipe implisit, sehingga konsistensi maupun validasi skema tidak dimungkinkan, dan juga ada masalah kompatibilitas di antara berbagai varian Markdown (flavor)
• Sintaks ekstensi seperti MDX meningkatkan daya ekspresi, tetapi justru menambah kompleksitas karena portabilitas dan standardisasi antar sistem yang kurang
• reStructuredText, AsciiDoc, DocBook, DITA dan lainnya menyediakan struktur eksplisit serta semantic markup yang memperkuat kemudahan penggunaan ulang dan keterbacaan oleh mesin
• Untuk dokumen kecil, Markdown sudah memadai, tetapi untuk pengelolaan dokumentasi berskala besar dan multikanal, diperlukan peralihan ke format yang terstruktur

---

Keterbatasan struktural Markdown

• Markdown memiliki sintaks sederhana yang mudah dibaca manusia, sehingga dapat membuat dokumen yang enak dilihat di GitHub atau situs statis
  • Namun, ia tidak dapat menjelaskan makna konten sehingga kekurangan informasi struktur yang dapat dipahami mesin
• Mesin pencari, LLM, IDE, agen AI, dan lainnya memanfaatkan struktur semantik dokumen, tetapi Markdown hanya menghasilkan tag HTML yang terbatas
• Markdown menimbulkan masalah inkonsistensi saat penggunaan ulang atau integrasi konten karena perbedaan sintaks antar platform
• Akibatnya, Markdown pada dasarnya adalah format pada tingkat penyebut bersama terendah, sehingga tidak cocok untuk pengelolaan dokumen yang kompleks

Masalah tipe implisit pada Markdown

• Markdown adalah format tanpa skema eksplisit atau definisi tipe, sehingga judul atau daftar yang sama bisa memiliki makna berbeda tergantung konteks
• Ada berbagai varian Markdown (flavor), sehingga muncul perbedaan rendering antar alat
  • Contoh: beberapa alat mendukung catatan kaki, sementara alat lain mengabaikannya
• MDX memperluas daya ekspresi dengan menyisipkan komponen React, tetapi portabilitasnya rendah karena masalah kompatibilitas antar sistem
• Ekstensi seperti ini adalah upaya untuk menutupi keterbatasan Markdown, tetapi pada akhirnya hanya solusi sementara yang tidak terstandarisasi

Pentingnya semantic markup

• Semantic markup menjelaskan makna konten, bukan bentuknya
  • Contoh: “langkah (step)” dan “item daftar” bisa terlihat sama secara visual, tetapi maknanya berbeda
• HTML5 memperkuat representasi struktural dengan memperkenalkan tag berbasis makna seperti <section>, <article>, <aside>
• Keunggulan utama semantic markup
  • Transformasi dan penggunaan ulang: konten yang sama dapat diubah ke berbagai format seperti HTML, PDF, dan ePub
  • Keterbacaan oleh mesin: LLM atau agen dapat mengenali struktur dengan jelas dan memberikan respons yang lebih akurat
• Karena Markdown tidak menyediakan informasi struktur semacam ini, terjadi kehilangan informasi saat pascapemrosesan atau konversi

Perbandingan format alternatif

• reStructuredText
  • Format yang digunakan di Sphinx dalam ekosistem Python, mengekspresikan makna struktural melalui directive dan role
  • Mendukung elemen struktur eksplisit seperti blok kode, catatan (note), dan referensi silang (:ref:)
  • Cocok untuk dokumentasi teknis berskala besar dan mendukung pembuatan HTML serta PDF
• AsciiDoc
  • Format teks semantik yang menyediakan attribute, konten kondisional, dan fitur include
  • Mendukung ekspresi yang dioptimalkan untuk dokumentasi teknis seperti NOTE, WARNING, elemen UI, dan penulisan pintasan keyboard
  • Dapat dikonversi ke HTML, PDF, ePub, DocBook, dan lainnya melalui AsciiDoctor
• DocBook (XML)
  • Model berbasis XML untuk publikasi teknis yang menyediakan sistem tag bermakna seperti <command>, <note>, <xref>
  • Mencakup tag yang dibutuhkan untuk dokumen profesional seperti glosarium, indeks, elemen UI, dan nama fungsi
  • Dapat dikonversi ke berbagai format keluaran melalui stylesheet XSLT
  • Menguntungkan untuk validasi struktur dokumentasi berskala besar dan pembuatan indeks
• DITA (Darwin Information Typing Architecture)
  • Struktur modular berbasis XML yang digunakan sebagai standar dokumentasi teknis perusahaan
  • Arsitektur XML berbasis topik yang mendefinisikan dengan jelas struktur prosedural seperti <task>, <step>
  • Digunakan sebagai standar pengelolaan dokumentasi perusahaan untuk penggunaan ulang konten (conref), pemfilteran, dan penerbitan multikanal
  • Mendukung otomatisasi rendering dan konversi melalui DITA Open Toolkit

Mengapa XML tetap diperlukan meski terlihat merepotkan

• Markdown memang ringan, tetapi merupakan solusi sementara yang tidak memiliki struktur, standar, dan konsistensi
• Jika Anda menambah kompleksitas pada Markdown dengan MDX, plugin, dan skrip kustom,
  mengadopsi format terstruktur secara langsung akan lebih stabil dalam jangka panjang

Jadi, apa yang sebaiknya dilakukan?

• Untuk dokumen kecil seperti README atau dokumen sekali pakai, Markdown sudah cukup, tetapi
  untuk dokumentasi berskala besar, dapat digunakan ulang, dan multikanal, reStructuredText, AsciiDoc, DocBook, dan DITA lebih cocok
• Jika Anda membutuhkan dokumen perencanaan, dokumentasi pengembang, penggunaan ulang, dan pengelolaan skala besar, pertimbangkan reST/AsciiDoc lalu DocBook/DITA
• Pendekatan yang ideal adalah menggunakan format dengan struktur paling kaya sebagai sumber, lalu mengonversinya ke Markdown bila perlu
• Markdown berguna sebagai format keluaran, tetapi jika digunakan sebagai sumber utama (source of truth), perluasan struktural akan sulit
• Yang optimal adalah menyimpan sumber dalam format dengan struktur makna yang kaya, dan menggunakan Markdown sebagai keluaran downstream