Saat menulis dokumentasi produk atau teknis, sangat penting untuk menyusun konten Anda dengan jelas dan menyajikannya secara visual dengan cara yang intuitif. Ini membantu pembaca dengan cepat memahami poin-poin utama dan mengurangi upaya yang diperlukan untuk memahami konten.
Apidog, sebagai alat manajemen API, tidak hanya memungkinkan manajemen dokumentasi API yang efisien tetapi juga memungkinkan tim untuk membuat dokumen produk tingkat profesional menggunakan sintaks Markdown yang fleksibel. Dokumentasi bantuan Apidog untuk pengguna dibangun menggunakan fitur Markdown Apidog.
Di bawah ini adalah 10 tips praktis untuk menulis dokumentasi produk dengan Markdown di Apidog.
1. Sesuaikan Judul Bilah Samping
Saat Anda membuat dokumen Markdown baru di Apidog, judul dalam dokumen Markdown secara default digunakan sebagai judul bilah samping, seperti yang ditunjukkan di bawah ini:
Jika Anda ingin judul bilah samping dan dokumen berbeda, Anda dapat menyesuaikannya secara terpisah.
Misalnya, Anda dapat menggunakan "Overview" sebagai judul bilah samping dan memberikan judul yang lebih spesifik untuk dokumen seperti "Desain API di Apidog".
Berikut cara mengaturnya: Di dalam dokumen Markdown, klik "Sidebar Title" dan ubah judulnya.
Menggunakan judul yang berbeda untuk bilah samping dan dokumen memiliki dua manfaat:
- Judul **bilah samping** tetap singkat dan rapi, menjaga struktur folder tetap bersih.
- Judul **dokumen** dapat lebih rinci dan deskriptif untuk kejelasan.
Saat Anda membagikan tautan dokumen di platform seperti Slack, judul dokumen muncul di pratinjau, membuat tautan terlihat lebih jelas dan mudah dipahami. Berikut contoh tampilannya di Slack:
2. Kutip Sumber Daya dan Skema Proyek
Apidog memudahkan untuk mengutip *endpoint*, dokumen, dan skema dari proyek Anda langsung ke file Markdown.
Untuk mengutip *endpoint* dan dokumen Markdown:
- Buka dokumen Markdown Anda dan klik "Insert Endpoint/Markdown in the project".
- Pilih sumber daya yang ingin Anda sisipkan (*endpoint* atau dokumen Markdown).
Konten yang dikutip akan secara otomatis tertaut ke sumber daya target dalam proyek, dan mengkliknya di tampilan pratinjau akan melompat ke halaman detail tersebut.
Untuk mengutip skema:
- Buka "Insert" → "Data Schema".
- Pilih yang diinginkan.
Setiap perubahan yang dilakukan tim Anda pada skema data akan secara otomatis disinkronkan dengan versi yang dikutip, memastikan dokumentasi Anda selalu terkini. Ini mencegah kebingungan dan kesalahan yang disebabkan oleh informasi usang.
Contoh kode:
<DataSchema id="4700682" />
3. Kontrol Perilaku Tautan dan Navigasi
Markdown Apidog mendukung berbagai jenis tautan, dan perilakunya dalam dokumentasi online berbeda:
- Beberapa tautan terbuka di **tab browser baru**
- Beberapa terbuka di **halaman saat ini**
- Lainnya langsung melompat ke **bagian tertentu** dalam dokumen menggunakan *anchor*
Memilih jenis tautan yang tepat membuat navigasi lebih mudah dan membantu pengguna dengan cepat menemukan informasi yang mereka butuhkan.
Di bawah ini, Anda akan menemukan detail tentang cara kerja setiap jenis tautan dan cara mengkonfigurasinya.
3.1 Tautan yang Terbuka di Halaman Saat Ini
Tautan yang ditambahkan melalui "Insert Endpoint/Markdown in the project" menghasilkan alamat yang dimulai denganapidog://link/pages/..., yang terbuka di halaman browser saat ini saat diklik.
Misalnya:
[Overview](apidog://link/pages/990068)
Cara mengaturnya: Klik tombol "Insert Endpoint/Markdown in the project" dan pilih *endpoint* atau dokumen yang diinginkan.
Tautan seperti `apidog://link/pages/...` dapat digunakan sebagai tautan normal di Markdown Apidog. Setelah diterbitkan atau dibagikan, tautan tersebut secara otomatis dikonversi menjadi alamat online aktual (misalnya, `https://xxx.apidog.io/xxx`) dan mendukung lompatan. Misalnya, dalam komponen "Card":
<Card title="Click here" href="apidog://link/pages/990068">
This is a card, click to jump to the target page
</Card>
3.2 Tautan yang Terbuka di Tab Baru
Setiap tautan yang tidak ditambahkan melalui "Insert Endpoint/Markdown in the project" akan terbuka di tab browser baru secara default. Misalnya:
[API-design first approach](https://docs.apidog.com/api-design-first-approach-533942m0)
3.3 Tautan *Anchor* yang Terbuka di Tab Baru
Untuk menautkan langsung ke bagian tertentu dalam Daftar Isi (TOC), tambahkan *anchor* (misalnya, `#xxx`) di akhir tautan Anda. Misalnya:
[these methods are the same as those used for inviting users to the team](https://docs.apidog.com/managing-team-members-613028m0#invitation-methods)
3.4 Tautan *Anchor* yang Terbuka di Halaman Saat Ini
Anda juga dapat menggunakan *anchor* dalam tautan proyek internal untuk melompat ke bagian tertentu dalam dokumen yang sama. Misalnya:
[these methods are the same as those used for inviting users to the team](apidog://link/pages/613028#invitation-methods)
Tautan *anchor* seperti `apidog://link/pages/613028#invitation-methods` hanya berfungsi setelah halaman **dibagikan atau diterbitkan**. Jika Anda mengklik tautan ini di klien Apidog sebelum menerbitkan, tidak ada yang akan terjadi karena tautan tersebut belum dikonversi menjadi jalur web yang dapat diakses.
Tautan di atas dapat dalam format Markdown atau HTML, misalnya:
Link that opens in the current page:
<a href="apidog://link/pages/533969">Design APIs in Apidog</a>
Link that opens in a new tab:
<a href="https://docs.apidog.com/design-apis-in-apidog-533969m0">Design APIs in Apidog</a>
Anchor link (opens in a new tab):
<a href="https://docs.apidog.com/design-apis-in-apidog-533969m0#design-apis">Design APIs in Apidog</a>
Anchor link (opens in the current page):
<a href="apidog://link/pages/533969#design-apis">Design APIs in Apidog</a>`4. Buat Tata Letak Berdampingan dengan Kontainer dan Kolom
Saat Anda perlu menunjukkan perbedaan antara versi, perbandingan fitur, atau informasi paralel, gunakan komponen "Container" yang bersarang dengan komponen "Column" untuk membuat tata letak berdampingan yang menarik secara visual.
Tata letak ini memudahkan pembaca untuk membandingkan konten secara sekilas, meningkatkan kejelasan dan komunikasi.
Misalnya:
Berikut cara mengaturnya: Di dokumen Markdown, pilih "Container", lalu "Multiple columns → 2 columns". Anda dapat mengisi setiap kolom dengan konten, seperti deskripsi “Old Version” dan “New Version”.
Contoh sintaks Markdown:
<Container>
<Columns>
<Column>
**Old Version**
</Column>
<Column>
**New Version**
</Column>
</Columns>
---
<Columns>
<Column>
Here is the old version content
<DataSchema id="4700681" />
</Column>
<Column>
Here is the new version content
<DataSchema id="8144258" />
</Column>
</Columns>
</Container>💡 Dalam Markdown di atas, <DataSchema id="xxxxxx" /> mengacu pada skema dalam proyek.
5. Gunakan Komponen Langkah untuk Panduan Visual
Untuk tutorial langsung atau panduan fitur, gunakan komponen "Step" di Markdown Apidog untuk memecah proses kompleks menjadi langkah-langkah sederhana yang mudah diikuti.
Desain terpandu ini membantu mengurangi kebingungan pengguna dan meningkatkan tingkat keberhasilan, terutama bagi pengguna baru atau saat menjelaskan fitur-fitur kompleks.
Komponen "Step" secara otomatis memberi nomor pada setiap langkah dan menambahkan isyarat visual untuk membuat proses menjadi jelas dan menarik.
Misalnya:
Berikut cara mengaturnya: Di dokumen Markdown, pilih komponen "Step" dan masukkan konten rinci untuk setiap langkah.
Contoh sintaks Markdown:
<Steps>
<Step title="First Step">
These are instructions or content that only pertain to the first step.
</Step>
<Step title="Second Step">
These are instructions or content that only pertain to the second step.
</Step>
<Step title="Third Step">
These are instructions or content that only pertain to the third step.
</Step>
</Steps>
6. Tingkatkan Tampilan dan Tata Letak Gambar
Di Markdown Apidog, menyisipkan gambar itu mudah. Anda dapat mengunggah gambar dari komputer Anda atau menempelkannya langsung ke editor.
Tautan gambar dapat berasal dari CDN pihak ketiga, seperti:
Baik sintaks Markdown maupun HTML didukung untuk menyisipkan gambar, misalnya:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog"/>Dengan HTML, Anda dapat menambahkan gaya CSS *inline*, seperti menentukan lebar, tinggi, dan pemusatan:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="width: 400px;display: block; margin: 0 auto"/>
// or
<div style="text-align: center;">
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="width: 400px;" />
</div>Dalam mode gelap, jika gambar memiliki transparansi, latar belakang akan default menjadi putih. Untuk menghilangkan latar belakang putih, gunakan CSS *inline*:
<img src="https://api.apidog.com/api/v1/projects/544525/resources/350490/image-preview" alt="Apidog" style="background-color: transparent;"/>Untuk membuat presentasi gambar lebih profesional dan indah, Anda dapat menambahkan latar belakang ke gambar:
<Background>
</Background>Atau tambahkan bingkai dan keterangan pada gambar:
<Frame caption="Appearance Preferences">
</Frame>7. Gunakan Tabel untuk Menampilkan Informasi Terstruktur dengan Jelas
Tabel adalah cara terbaik untuk menyajikan data terstruktur. Markdown Apidog mendukung sintaks tabel Markdown standar dan memungkinkan gaya HTML untuk membuat tabel lebih profesional dan indah.
Tabel dasar:
| Feature | Status | Description |
| --- | --- | --- |
| User Auth | ✅ Done | Supports multiple login methods |
| Data Sync | ⚠️ In Progress | Expected next week |
| Report Export | ❌ Not Started | Planned for Q3 |Sesuaikan lebar kolom: Gunakan gaya HTML *inline* untuk mengontrol lebar kolom dan menghindari tata letak yang berantakan.
| <div style="width: 100px;">Feature</div> | <div style="width: 100px;">Status</div> | <div style="width: 200px;">Descriptions</div> |
| --- | --- | --- |
| User Auth | ✅ Done | Supports multiple login methods |
| Data Sync | ⚠️ In Progress | Expected next week |
| Report Export | ❌ Not Started | Planned for Q3 |
8. Gunakan Blok Akordeon untuk FAQ
Blok akordeon ideal untuk mengatur FAQ atau detail yang tidak penting. Struktur ini memungkinkan pembaca untuk memperluas konten sesuai kebutuhan, menjaga halaman tetap rapi dan tidak berantakan.
Blok akordeon sangat cocok untuk FAQ, fitur opsional, konfigurasi lanjutan, pemecahan masalah, dll., memungkinkan pengguna untuk dengan cepat mengakses informasi penting tanpa kehilangan detail.
Penggunaan dasar:
`<Accordion title="How to reset password?"> 1. Klik “Lupa Kata Sandi” di halaman login 2. Masukkan alamat email terdaftar Anda 3. Klik “Kirim Email Reset” 4. Klik tautan reset di email dan atur kata sandi baru </Accordion>Atur status default (ciut):
<Accordion title="Advanced Settings (Optional)" defaultOpen={false}> Bagian ini mencakup opsi lanjutan namun tidak penting untuk pengguna dengan kebutuhan khusus. - Header permintaan kustom - Pengaturan server proxy - Optimasi kinerja </Accordion>
9. Gunakan Pemberitahuan untuk Menyoroti Informasi Penting
Blok pemberitahuan dan sorotan sangat bagus untuk menekankan informasi penting seperti catatan, tips, atau peringatan, memastikan pengguna tidak melewatkan konten utama.
Pemberitahuan:
:::tip
Ini adalah pemberitahuan tip
:::
:::warning
Ini adalah pemberitahuan peringatan
:::
:::caution
Ini adalah pemberitahuan perhatian
:::
:::danger
Ini adalah pemberitahuan bahaya
:::
:::check
Ini adalah pemberitahuan cek
:::
:::info
Ini adalah pemberitahuan info
:::
:::note
Ini adalah pemberitahuan catatan
:::
Blok sorotan:
:::highlight purple 💡
Ini adalah konten yang disorot
:::
:::highlight yellow 👋
Ini adalah konten yang disorot
:::
:::highlight orange 🚀
Ini adalah konten yang disorot
:::
:::highlight red 🌟
Ini adalah konten yang disorot
:::
:::highlight gray 🚀
Ini adalah konten yang disorot
:::
:::highlight blue 📌
Ini adalah konten yang disorot
:::
:::highlight green 🔑
Ini adalah konten yang disorot
:::
10. Tambahkan Fitur *Hover* dan Salin ke Istilah
Dengan komponen `Tooltip`, Anda dapat menampilkan definisi saat mengarahkan kursor ke teks.
<Tooltip tip="Ini adalah tip!"> Arahkan kursor ke sini untuk tip</Tooltip>Dengan komponen `CopyToClipboard`, Anda dapat menyalin teks dengan mengklik.
<CopyToClipboard >Klik di sini untuk menyalin teks</CopyToClipboard>Gabungkan `Tooltip` dan `CopyToClipboard` untuk "tip *hover* dan salin":
<Tooltip tip="Ini adalah tip, dan Anda bisa menyalin!"><CopyToClipboard >Klik di sini untuk menyalin teks</CopyToClipboard></Tooltip>
Kesimpulan
Dengan menggunakan fitur Markdown Apidog ini secara fleksibel, Anda dapat membuat dokumentasi yang profesional dan menarik secara visual. Dokumentasi yang baik mengurangi biaya komunikasi, meningkatkan efisiensi pengembangan, dan menunjukkan profesionalisme tim serta kualitas produk Anda. Dokumentasi yang sangat baik adalah bagian penting dari pengalaman produk dan layak untuk diinvestasikan. Untuk tips lebih lanjut, lihat Dokumentasi Markdown Apidog.