Panduan penulisan dokumentasi teknis untuk Divisi IT — konsisten, jelas, dan mudah dirawat

Dokumentasi yang baik adalah investasi. Standar ini berlaku untuk semua dokumen teknis yang dibuat oleh Divisi IT.

Prinsip Penulisan

Tujuan jelas — setiap dokumen harus jawab satu pertanyaan spesifik
Pembaca adalah raja — tulis untuk orang yang baca, bukan untuk diri sendiri
Jargon itu boleh, tapi jelaskan — akronim wajib ditulis lengkap di pertama muncul
Code > Screenshot — kode bisa di-copy, screenshot nggak
Stay alive — dokumen usang lebih bahaya dari tidak ada dokumen

Format Dokumen

Semua dokumentasi ditulis dalam Markdown dengan format sebagai berikut:

---
title: Judul Dokumen
description: Deskripsi singkat (1-2 kalimat)
---

## Pendahuluan

Konteks: kenapa dokumen ini ada, siapa target pembaca.

## Isi

Gunakan heading bertingkat (h2 → h3 → h4). Jangan lompat dari h2 ke h4.

## Referensi

- Link ke dokumen terkait
- Link ke kode sumber

Heading Structure

Level	Penggunaan
`h1`	Title (otomatis dari frontmatter)
`h2`	Section utama
`h3`	Sub-section
`h4`	Detail lebih lanjut (jarang)

Tabel

Gunakan tabel untuk data terstruktur. Pastikan rapi:

| Parameter | Tipe | Wajib | Deskripsi |
|---|---|---|---|
| `user_id` | string | ✅ | UUID user |
| `role` | string | ❌ | Default: "viewer" |

Code Block

Selalu sertakan bahasa untuk syntax highlighting:

// ✅ Good — dengan language
app.get("/health", (req, res) => res.json({ status: "ok" }));

    // ❌ Bad — tanpa language
    app.get("/health", (req, res) => res.json({ status: "ok" }));

Callouts

Gunakan blockquote untuk callouts penting:

⚠️ Warning: Jangan pernah commit .env ke repository.

💡 Tip: Gunakan npm run lint sebelum commit.

📝 Note: Dokumen ini perlu di-review setiap 3 bulan.

Standar Dokumentasi