Cara dokumentasi NextPDF disusun

Sekilas pandang

Manual NextPDF mengikuti kontrak tetap. Setiap halaman memiliki satu topik, satu mode Diataxis, dan satu jenis halaman. Setiap jenis halaman memiliki serangkaian judul tingkat 2 wajib. Sejumlah kecil manifes dan gate menjaga struktur tetap konsisten seiring berkembangnya manual.

Halaman ini merangkum sistem tersebut agar Anda dapat menempatkan kontribusi dengan tepat. Kontrak normatif lengkap, termasuk daftar judul persis, aturan kutipan, dan prosedur penghubungan gate, terdapat di dokumen tata kelola internal docs/style/expansion-standard.md. Baca halaman ini terlebih dahulu. Rujuk dokumen tersebut saat menulis.

Memilih jenis halaman

Terapkan aturan berikut secara berurutan untuk memutuskan apakah Anda perlu menambahkan halaman baru atau memperluas halaman yang sudah ada:

1. Jika materinya merupakan topik tersendiri yang tidak akan pembaca harapkan berada di halaman yang sudah ada, tambahkan halaman baru.
2. Jika materinya melengkapi topik pada halaman yang sudah ada, perluas halaman tersebut.
3. Jika materinya merupakan detail mendalam yang akan membuat halaman pemasangan, panduan cepat, atau tugas terlalu panjang, pindahkan ke halaman terpisah dan tautkan ke sana.
4. Jika tidak, perluas halaman yang sudah ada.

Setelah Anda memastikan halaman tersebut memang diperlukan, tetapkan mode Diataxis-nya. Mode tersebut menentukan jenis halaman:

• Tutorial mengajari pemelajar. Gunakan panduan tugas yang ditulis seperti resep.
• Cara-melakukan membantu pembaca yang sudah cakap menyelesaikan tugas. Gunakan panduan tugas, panduan API server, atau panduan software development kit.
• Referensi menyajikan fakta yang presisi. Gunakan referensi API atau halaman indeks.
• Penjelasan membangun pemahaman. Gunakan panduan pengembang atau panduan fitur premium.

Bahasa yang lugas menjadi dasar bagi setiap mode, bukan mode tersendiri.

Katalog jenis halaman

Kontrak manual mengenali jenis-jenis berikut. Gunakan kembali jenis yang sudah ada setiap kali halaman Anda menyertakan tabel API. Perkenalkan jenis berlabel-saja baru hanya untuk halaman tanpa tabel API.

• Jenis indeks: section-index, api-index, extension-index.
• Jenis referensi: api-reference. Gunakan kembali jenis ini untuk halaman mana pun yang memiliki tabel API standar, termasuk referensi server dan Python SDK.
• Jenis penjelasan: developer-guide. Gunakan kembali jenis ini untuk uraian arsitektur, siklus hidup, dan titik ekstensi, termasuk panduan server dan Python SDK.
• Jenis berlabel-saja baru: premium-feature-guide dan task-guide, keduanya untuk halaman tanpa tabel API.

Setiap halaman diawali dengan ## At a glance. Setiap halaman api-reference memuat tabel API bersama dan judul Development notes. Judul wajib merupakan judul tingkat 2, masing-masing pada barisnya sendiri. Anda boleh menambahkan judul lain di bawahnya.

Daftar periksa penulisan

Saat menulis halaman, penuhi dua daftar periksa berikut. Standar internal menyatakan setiap butir secara normatif dan menautkannya ke standar pendukungnya.

Keramahan bagi pengembang:

• Gunakan contoh yang dapat dijalankan dari examples/ atau tests/Cookbook, dan tambahkan info string title= pada setiap blok berpagar.
• Sebutkan prasyarat di front-matter dan di bagian pembuka.
• Tampilkan keluaran yang diharapkan untuk setiap contoh yang menghasilkannya.
• Pastikan blok siap disalin dan ditempel: satu bahasa per blok, nama lengkap pada penggunaan pertama, dan tanpa karakter prompt di akhir.
• Tampilkan kode yang aman secara default: contoh produksi menggunakan try/catch dengan eksepsi NextPDF yang paling spesifik dan tidak pernah menggunakan catch kosong.
• Akhiri dengan tautan lanjutan dan atur front-matter related:.

Kesiapan penerjemahan:

• Tuliskan satu gagasan per kalimat agar terjemahan mesin tetap terkontrol.
• Jaga judul dan label tetap singkat karena sebagian besar bahasa sasaran cenderung lebih panjang.
• Hindari idiom.
• Pertahankan nama simbol, kunci konfigurasi, flag CLI, dan nama eksepsi dalam format kode; nama standar seperti PDF/A-4, PAdES, dan eIDAS tidak pernah diterjemahkan.
• Atur i18n_ready dan xliff_segments secara jujur, dan tulislah dalam Unicode NFC.

Untuk gaya bahasa, contoh kode, terminologi, dan gaya kutipan, ikuti lembar penggantian gaya yang telah disahkan dan dirujuk oleh standar internal.

Penghubungan gate

Ikuti prosedur berurutan berikut untuk menghubungkan halaman baru:

1. Buat kerangka halaman agar front-matter-nya sesuai dengan skema situs.
2. Tulis isi sesuai dengan judul yang diwajibkan oleh jenis halaman tersebut.
3. Tambahkan entri { path, owner, kind, headings[] } ke docs/manual-contract.json. Path tersebut relatif terhadap src/content/docs, menggunakan garis miring depan, tanpa garis miring di awal dan tanpa ...
4. Untuk referensi API, tambahkan simbol halaman tersebut ke docs/api-coverage-manifest.json; setiap simbol harus muncul di halaman dan tersedia di sumber.
5. Perbarui docs/source-manifest.json hanya ketika halaman berasal dari repositori sumber yang baru.
6. Tambahkan halaman ke grup bilah samping yang tepat di astro.config.mjs sebagai entri eksplisit.
7. Tambahkan baris cakupan lokal dengan seluruh ketujuh belas sel lokal diatur ke missing untuk halaman yang hanya berbahasa Inggris.
8. Jalankan gate dokumentasi, proses build, dan pemeriksaan anggaran kinerja.

Halaman milik situs berada di bawah src/content/docs, menetapkan owner ke nextpdf-docs, dan tidak pernah memuat penanda agregasi. Halaman teragregasi berasal dari repositori sumber. Flag publikasinya berada di front-matter sumber, karena itu Anda menyuntingnya di sana, bukan di sini.

Lihat juga

• Integrasi: contoh terbesar penerapan struktur manual di banyak paket.
• Dokumen tata kelola internal docs/style/expansion-standard.md memuat kontrak lengkap: daftar judul persis untuk setiap jenis halaman, aturan kutipan, dan prosedur penghubungan gate yang lengkap.