---
name: technical-documentation
description: Gunakan skill ini sebagai panduan komprehensif untuk menulis dokumentasi teknis kelas korporat (corporate-grade) yang profesional dan modern, baik dalam Bahasa Indonesia maupun Bahasa Inggris. Mengatur tata bahasa teknis, penulisan istilah asing (miring), arsitektur dokumen (README, API reference, System Design, CALK), dan standarisasi penulisan.
---

# 📄 Dokumentasi Teknis Kelas Korporat (*Corporate-Grade Technical Documentation*)

## 🎯 Standar Utama Dokumentasi

Dokumentasi dalam proyek kelas korporat (*corporate-grade*) harus memenuhi empat pilar utama:
1. **Kejelasan (*Clarity*):** Menghindari ambiguitas, menggunakan kalimat yang lugas, dan memiliki struktur hierarki yang logis.
2. **Keterbacaan (*Readability*):** Menggunakan format visual yang konsisten, tabel pembanding, daftar berpoin, dan diagram alur.
3. **Kemudahan Penelusuran (*Traceability*):** Setiap perubahan kebijakan sistem, *skema basis data* (*database schema*), atau alur bisnis harus dapat ditelusuri kembali ke dokumen spesifikasi awal.
4. **Satu Sumber Kebenaran (*Single Source of Truth*):** Menghindari duplikasi informasi di beberapa file berbeda untuk mencegah inkonsistensi data ketika sistem diperbarui.

---

## 🏛️ Arsitektur Dokumen Proyek (*Project Document Architecture*)

Setiap repositori berskala besar wajib menyediakan struktur dokumentasi standar berikut:

```mermaid
graph TD
    Root[Root Directory] --> README["README.md (Entry Point & Setup)"]
    Root --> AGENTS["AGENTS.md / GEMINI.md (AI Context Guide)"]
    Root --> DOCS_DIR["docs/ (Comprehensive Guides)"]
    
    subgraph Docs Folder Structure
        DOCS_DIR --> ARCH["architecture/ (System Design & Flow)"]
        DOCS_DIR --> API["api/ (Endpoint Contracts & Schemas)"]
        DOCS_DIR --> DEPLOY["deployment/ (Infrastructure & CI/CD)"]
        DOCS_DIR --> OPERATIONAL["operational/ (UAT, SLA, & Runbooks)"]
    end
```

### 1. *README.md (Quick Start & Integration)*
Berfungsi sebagai gerbang utama bagi pengembang baru. Wajib memuat:
*   *Prerequisites* (kebutuhan sistem minimal).
*   Langkah-langkah instalasi cepat (*quick start guide*).
*   Skema struktur folder tingkat tinggi.
*   Panduan integrasi cepat dengan *tooling* pengembangan.

### 2. *System Architecture Document (SAD)*
Dokumen tingkat tinggi yang menjelaskan keputusan arsitektur sistem. Wajib memuat:
*   *Component diagram* untuk menggambarkan hubungan antar layanan (*microservices*).
*   *Sequence diagram* untuk alur data krusial (misalnya proses pembayaran atau autentikasi).
*   Pernyataan trade-off arsitektur (*Architectural Decision Records* / ADR).

### 3. *API Contract / Reference Guide*
Spesifikasi teknis untuk setiap antarmuka pemrograman aplikasi (*application programming interface* / API). Wajib memuat:
*   Alamat *endpoint*, metode HTTP (*HTTP methods*), dan header wajib (*required headers*).
*   Skema *payload* permintaan (*request payload schema*) menggunakan *JSON* atau *Pydantic model*.
*   Contoh respon sukses (*success response*) dan berbagai skenario respon kesalahan (*error response*).

---

## ✍️ Aturan Kebahasaan & Penulisan (*Linguistic & Formatting Rules*)

> [!IMPORTANT]
> **Aturan Penulisan Istilah Asing:**
> Semua istilah asing, kosakata Bahasa Inggris, frasa teknis, nama *framework*, atau pustaka (*libraries*) yang ditulis di dalam dokumen wajib menggunakan format **cetak miring (*italics*)** untuk menjaga estetika dokumen dan standar profesionalitas.

### 1. Perbandingan Penggunaan Istilah Asing (*Italicized English Terms*)

| Bahasa Indonesia Formal | Istilah Inggris (Wajib Cetak Miring) | Contoh Penerapan dalam Kalimat |
| :--- | :--- | :--- |
| Antarmuka Pengguna | *User Interface* (UI) | Tampilan *user interface* harus responsif di semua perangkat. |
| Pengolahan Latar Belakang | *Background Processing* | Gunakan Celery untuk menjalankan *background processing* skala besar. |
| Batas Waktu Sesi | *Session Timeout* | Sistem akan memicu *session timeout* setelah lima menit tidak ada aktivitas. |
| Penyeimbang Beban | *Load Balancer* | Konfigurasikan *load balancer* untuk mendistribusikan lalu lintas data. |
| Lingkungan Pengembangan | *Development Environment* | Pastikan *environment variables* di *development environment* sudah tervalidasi. |

### 2. Gaya Bahasa & Nada Bicara (*Tone of Voice*)
*   **Objektif dan Pihak Ketiga:** Gunakan sudut pandang pihak ketiga atau kalimat pasif formal. Hindari kata ganti personal seperti "saya", "kami", atau "kita" dalam dokumentasi teknis sistem.
    *   *Salah:* "Kami merekomendasikan Anda menggunakan uv untuk menginstal package."
    *   *Benar:* "Sangat direkomendasikan untuk menggunakan *uv package manager* guna memastikan efisiensi instalasi dependensi."
*   **Tindakan dan Hasil (*Action-Oriented*):** Setiap langkah instruksi operasional harus diawali dengan kata kerja imperatif yang jelas.
    *   *Salah:* "Database harus dibuat setelah Anda menjalankan perintah docker."
    *   *Benar:* "Jalankan perintah *docker-compose* untuk menginisialisasi kontainer basis data."

### 3. Humanisasi & Eliminasi Pola AI (*Humanizing & Eliminating AI Signatures*)
*   **Larangan Daftar Berpoin Tanda Hubung (`-`) Berulang:** Hindari penyusunan dokumen yang didominasi oleh deretan poin-poin menggunakan tanda hubung (`-`) tanpa analisis mendalam. Gaya penulisan ini merupakan ciri khas teks buatan kecerdasan buatan (*AI-generated text*) yang malas dan tidak natural.
*   **Preferensi Prosa, Tabel, dan Daftar Bernomor:** Gunakan paragraf naratif terstruktur (*humanized prose*) untuk menjelaskan konsep, tabel komparatif untuk perbandingan data, dan daftar bernomor (`1.`, `2.`, `3.`) untuk urutan langkah logis.
*   **Ketelitian Tanpa Batas (*Zero Gaps, Zero Miss, & Zero Inconsistency*):** Dokumentasi harus merinci setiap transisi keadaan sistem secara utuh. Setiap masukan (*input*) wajib memiliki luaran (*output*) yang terdefinisi dengan jelas tanpa menyisakan asumsi kosong atau ketidaksesuaian logis.

---

## 📊 Visualisasi & Diagram (*Visualization Standards*)

Gunakan *Mermaid.js* untuk menyisipkan diagram interaktif langsung di dalam dokumen *Markdown*. Hindari penggunaan gambar statis (*screenshots* / *static image files*) untuk diagram arsitektur agar dokumen mudah diperbarui di masa mendatang tanpa kehilangan kualitas gambar.

### Contoh Diagram Alur Autentikasi (*Authentication Flowchart*)

```mermaid
sequenceDiagram
    autonumber
    actor Client as Client App
    participant Proxy as Edge Proxy (proxy.ts)
    participant Server as API Server (Node/Django)
    participant DB as Database Session

    Client->>Proxy: Kirim request dengan session cookie
    Proxy->>Proxy: Cek format token JWT / Session ID
    alt Format Invalid
        Proxy-->>Client: Return 401 Unauthorized
    else Format Valid
        Proxy->>Server: Forward request ke data layer
        Server->>DB: Query session detail & role check
        alt Otorisasi Gagal (IDOR/Forbidden)
            Server-->>Client: Return 403 Forbidden
        else Akses Disetujui
            Server-->>Client: Return 200 OK dengan payload data
        end
    end
```

---

## 📋 Templat Standar Dokumentasi (*Standard Documentation Templates*)

### 1. Templat *API Endpoint Reference*
```markdown
### `POST /api/v1/auth/register`

Mendaftarkan akun pengguna baru ke dalam sistem multi-penyewa (*multi-tenant system*).

#### Header Wajib (*Required Headers*)
*   `Content-Type: application/json`
*   `X-Tenant-ID: string` (Sesuai dengan ID entitas perusahaan pengguna)

#### Payload Permintaan (*Request Payload*)
```json
{
  "email": "user@example.com",
  "password": "SecurePassword123!",
  "profile": {
    "full_name": "Arief Maulana",
    "phone_number": "+6281234567890"
  }
}
```

#### Respon Sukses (*Success Response - 201 Created*)
```json
{
  "success": true,
  "data": {
    "user_id": "usr_9f8d7e6c",
    "email": "user@example.com",
    "created_at": "2026-07-08T15:00:00Z"
  }
}
```

#### Respon Kesalahan (*Error Response - 422 Unprocessable Entity*)
```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "Format alamat email tidak valid",
    "details": {
      "email": [
        "Enter a valid email address."
      ]
    }
  }
}
```
```

---

## ❌ Hal yang Harus Dihindari dalam Dokumentasi Teknis

*   **Menulis Istilah Teknis Asing Tanpa Format Miring:** Menulis istilah seperti *middleware*, *setup*, *query*, atau *request* menggunakan font tegak biasa tanpa tanda miring.
*   **Penggunaan Daftar Berpoin Tanda Hubung (`-`) Berlebihan:** Menyusun seluruh penjelasan teknis rumit hanya dengan daftar *bullet points* tanda hubung (`-`) berturut-turut tanpa didukung oleh narasi (*humanized prose*) yang matang.
*   **Menggunakan Tanggal Relatif:** Menggunakan kata "kemarin", "bulan depan", atau "saat ini". Selalu gunakan format tanggal absolut berbasis standar *ISO 8601* (misalnya: `YYYY-MM-DD`).
*   **Menulis Dokumentasi Stateless:** Menulis panduan instalasi tanpa memberikan penjelasan langkah verifikasi kesuksesan instalasi (*verification steps*).
*   **Menyimpan Kredensial Nyata:** Menulis contoh token API (*API key*), kata sandi database, atau kunci privat (*private key*) yang asli ke dalam file dokumentasi. Selalu gunakan nilai contoh (*mock values* / *dummy placeholders*).