ERP ID · Help

Authoring guide

Cara menulis artikel dokumentasi agar terbaca baik oleh manusia maupun oleh Ana.

Diperbarui

Setiap artikel di situs ini ditulis sekali dalam MDX dan dibaca oleh dua audiens: manusia (yang membaca halaman jadinya) dan Ana (asisten AI, yang membaca ekstrak terstruktur). Dua aturan berikut membuat satu berkas melayani keduanya.

The two rules

The component vocabulary

Tujuh komponen. Tahan diri untuk menambah yang kedelapan tanpa alasan kuat — setiap komponen baru adalah satu bentuk lagi yang harus dipahami ekstraktor Ana.

Conceptcomponentrequired

Model berpikir atau “ini apa”. Dipakai untuk satu paragraf konseptual di awal sebuah tugas. Biasanya satu <Concept> per artikel.

Stepcomponentrequired

Satu instruksi tunggal. Bernomor. Atribut: n (wajib), action (click / open / select / enter / toggle / drag / confirm / wait), target (nama tombol/kolomnya).

Screenshotcomponentrequired

Gambar dengan teks alt deskriptif yang wajib diisi. Caption bersifat opsional.

Warningcomponent

Hal yang bisa menyebabkan kehilangan data, salah nominal, atau tindakan yang tidak bisa dibatalkan.

Tipcomponent

Jalan pintas atau trik opsional. Isinya boleh dilewati.

Prerequisitecomponent

Tautan ke artikel lain yang sebaiknya diselesaikan pembaca lebih dulu. Tampil sebagai kartu bertaut; bagi Ana ini adalah sisi dalam graf.

Fieldcomponent

Entri referensi untuk satu kolom pada sebuah formulir. Atribut: name, type, required, default.

Frontmatter is not optional

Frontmatter setiap artikel divalidasi skema Zod saat build. Satu kolom wajib yang hilang akan menggagalkan build. Frontmatter menopang:

  • Navigasi manusia — halaman per grup, aplikasi, dan peran
  • Pencarian Ana — filter (app=crm, role=sales_rep) mempersempit pencarian ke korpus yang tepat

What Ana sees

Saat Anda menyimpan artikel, ekstraktor menghasilkan satu berkas JSON dengan satu chunk per komponen. Sebuah <Step> menjadi:

{
  "id": "crm.convert_lead_to_opportunity#step-2",
  "type": "step",
  "n": 2,
  "action": "click",
  "target": "Tombol Ubah",
  "text": "Klik Ubah di bilah aksi atas pada kartu prospek mana pun.",
  "metadata": { "app": "crm", "roles": ["sales_rep"], "task": "convert_lead_to_opportunity" }
}

Inilah yang dipakai Ana sebagai dasar jawabannya. Kalau teks <Step> Anda berbunyi "Klik saja", Ana akan mengutip "Klik saja" — tanpa tahu apa yang dimaksud.

Chat WhatsApp