Menulis Dokumentasi dengan Docusaurus — Part 1: Cara Install dan Penggunaan

Saat melanjutkan pengembangan sebuah software, terkadang kita kebingungan karna minimnya dokumentasi dari pengembang sebelumnya.

Oleh karena itu, penting bagi tim pengembangan untuk memberikan perhatian yang cukup pada pembuatan dokumentasi yang komprehensif, sehingga dapat memberikan panduan yang jelas dan berguna bagi pengembang yang akan datang atau bahkan untuk anggota tim sendiri.

Documentation is like food: when it is good, it is very, very good; and when it is bad, it is better than nothing.

Photo by Sam J from Pexels: https://www.pexels.com/photo/white-paper-folders-with-black-tie-1764956/

Terdapat beragam alat yang dapat digunakan untuk membuat dokumentasi, seperti Docusaurus, Gatsby, VitePress, dan Gitbook. Pada kesempatan ini, kita akan membahas Docusaurus karena alat ini memiliki berbagai keunggulan, seperti komunitas yang besar, beragam plugin, dan tentu saja gratis.

Docusaurus adalah sebuah static-site generator, dimana dapat digunakan untuk membuat single-page application yang berbasis React, yang menyediakan berbagai fitur untuk membuat situs dokumentasi.

Prerequisite

• Nodejs versi 18 atau lebih tinggi

Installation

Jalankan perintah dibawah untuk membuat situs Docusarus yang siap pakai:

npx create-docusaurus@latest my-documentation classic

• Pada command diatas, my-documentation adalah nama situs dokumentasi yang akan kita buat.
• Terdapat juga classic dimana itu adalah template yang digunakan, ada beberapa pilihan theme yang bisa dilihat disini.

Kita juga bisa menggunakan Typescript, dengan menambahkan --typescript dibelakangnya.

npx create-docusaurus@latest my-documentation classic --typescript

Selanjutnya menjalankan situs docusaurus-nya

cd my-documentation

npm start

Situs Docusaurus dapat diakses melalui http://localhost:3000

Halaman utama Docusaurus

Selamat! situs dokumentasi sudah jadi dan tinggal menulis kontennya

Cara Menulis di Docusaurus

Sebelum kita menulis, kita harus memahami dulu bagaimana project structure-nya terlebih dahulu.

my-documentation
├── blog
│   ├── 2019-05-28-hola.md
│   ├── 2019-05-29-hello-world.md
│   └── 2020-05-30-welcome.md
├── docs
│   ├── doc1.md
│   ├── doc2.md
│   ├── doc3.md
│   └── mdx.md
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── styles.module.css
│       └── index.js
├── static
│   └── img
├── docusaurus.config.js
├── package.json
├── README.md
├── sidebars.js
└── yarn.lock

Karna kita hanya akan menulis dokumentasi, kita cukup fokus ke folder docs yang ada didalam folder my-documentation. Disitulah tempat kita akan menulis dokumentasi.

Setiap halaman ditandai dengan satu file yang ditulis menggunakan format markdown dengan format file .mdatau .mdx . Format ini mudah dipelajari dan sudah umum digunakan, kamu bisa mempelajari cara penulis markdown lebih lanjut disini.

Mari kita coba menulis di docusaurus

1. Pertama buat file ai.md didalam folder docs .

Contoh file ai.md

2. Lalu tuliskan seperti diatas.

3. Lalu kita lihat kembali di halaman docusaurus kita, buka pada menu Tutorial, maka tab Artificial Intelligent akan muncul, dan dihalaman tersebut akan muncul tulisan yang telah kita buat.

Hasil file ai.md

Selamat! Kamu berhasil menulis di docusaurus!

Selanjutnya, lanjutkan dengan menulis dan melengkapi dokumentasinya sesuai kebutuhan. Kamu dapat menjelaskan setiap langkah atau konsep dengan rinci, menyertakan contoh penggunaan, dan memberikan panduan yang mudah dipahami. Pastikan untuk mencakup informasi yang relevan dan berguna agar pengguna dapat memahami dan mengimplementasikannya dengan baik.

Jangan ragu untuk memanfaatkan fitur-fitur Docusaurus yang tersedia untuk meningkatkan pengalaman pembaca, seperti penataan halaman, pengelompokan konten, atau menambahkan plugin.

Pada tutorial selanjutnya, kita akan membahas cara menambah fitur searching pada docusaurus dengan mengintegrasikan typesense, sehingga kita bisa melakukan pencarian di situs dokumentasi kita.

References

Introduction | Docusaurus