Workflow Documentasi

Monorepo di chapter sebelumnya menyimpan kode tiga aplikasi dalam satu rumah. Workflow terakhir membawa kita ke repository yang isinya justru bukan kode: panduan pengguna, buku pegangan tim, dokumentasi produk — barang yang dijual adalah kata-katanya. Dokumentasi semacam ini sering dibuang ke wiki tanpa riwayat lalu diam-diam membusuk: halaman versi lama masih tayang, dan penghapusan satu paragraf sore hari menghapus pekerjaan orang lain tanpa jejak. Meletakkan dokumen di repository Git membalik semuanya: setiap perubahan punya penulis, waktu, dan pesan; tulisan panjang ditimbang lewat pull request; terbitan dokumen bernomor versi seperti rilis perangkat lunak. Prinsipnya satu kalimat: perlakukan dokumen sebagai kode.

Piramida README: Ringkas di Atas, Rinci di Bawah #

Pembaca dokumentasi datang dengan kebutuhan berbeda: ada yang hanya ingin tahu apa produknya (tiga puluh detik), hendak memasang (tiga menit), atau mencari jawaban satu detail (tiga puluh menit). README yang sehat menyusun dirinya seperti piramida terbalik ala penulisan berita: ringkasan di baris paling atas, rincian makin ke bawah — pembaca berhenti tepat ketika pertanyaannya terjawab. README dari sesi kita nanti berbentuk begini:

text
# Panduan Toko Budi

Aplikasi kasir warung kopi. Pasang, atur, jalankan.

- [Instalasi](docs/instalasi.md)
- [Konfigurasi](docs/konfigurasi.md)

Lapisannya terbaca dari atas: judul dan satu kalimat identitas menjawab “apa ini dan untuk siapa”; daftar tautan menjadi peta topik; dan detail lengkap tidak pernah menumpuk di README — ia hidup di satu berkas per topik di docs/. Detail yang menumpuk di README mengubur ringkasan di bawah layar pertama.

Empat Artefak dan Perannya #

Repository dokumentasi yang sehat berdiri di atas empat artefak tetap — perannya berbeda, pembacanya juga berbeda:

Artefak	Perannya	Dibaca oleh
`README.md`	pintu masuk: identitas produk dan peta topik	pengguna baru, tiga puluh detik
`docs/` per topik	panduan lengkap: instalasi, konfigurasi, pemecahan masalah	pembaca yang sedang mengerjakan sesuatu
`CHANGELOG.md`	versi dokumen: apa yang berubah di tiap terbitan	pembaca yang membandingkan antar versi
`CONTRIBUTING.md`	aturan penulis: gaya commit, alur branch, tempat diskusi	calon kontributor dokumen

CHANGELOG memakai format terstruktur persis pola chapter Changelog , dan CONTRIBUTING membawa konvensi yang di chapter Workflow Open Source terbukti menahan kekacauan kontribusi.

Commit docs: dan Versi Dokumen #

Perubahan dokumen diberi type docs: dari Conventional Commits — bentuknya semisal docs: perbarui panduan instalasi. Manfaatnya dua: pada repository dokumen murni seluruh log terbaca sebagai satu golongan, dan pada repository campuran, filter type memisahkan edit kata dari edit kode sehingga changelog bisa dirangkai terpilah. Terjemahan resminya ada di spesifikasi Conventional Commits .

Versi dokumen mengikuti pola rilis yang sudah dikenal: tiap terbitan dicatat di CHANGELOG lalu ditandai tag annotated — v1.1.0 berarti “dokumen pada keadaan ini diterbitkan”, dan pembaca yang melapor kekeliruan cukup menyebut versi yang dibacanya. Perilaku tag annotated dirinci di dokumentasi git tag .

Tulisan Panjang: Branch dan Reviewer sebagai Editor #

Typo diperbaiki langsung di main — biayanya sekecil isi perubahannya. Tulisan panjang tidak: bab baru atau panduan yang dirombak dikerjakan di branch tersendiri lalu dibuka sebagai pull request, persis pola Pull Request . Yang khas dari workflow dokumen ada di meja reviewer: ia editor, bukan penilai kode — menimbang kejelasan, audiens, dan akurasi, bukan gaya sintaks. Siklusnya sama dengan Code Review : komentar masuk, penulis menjawab lewat commit tambahan di branch yang sama, dan halaman pull request otomatis memuat iterasinya.

Sesi Nyata: Dua Bagian Baru Lewat Pull Request #

Repository panduan-toko mendokumentasikan aplikasi kasir warung kopi. Budi memegang peran maintainer, Siti menjadi penulis. Budi merintis kerangka dan menyiapkan remote bare — pola yang sama dengan sesi Workflow Tim Kecil :

bash
mkdir dok-toko && cd dok-toko
mkdir budi && cd budi
git init -b main
git config user.name "Budi Santoso"
git config user.email "[email protected]"
mkdir docs
printf '# Panduan Toko Budi\n\nAplikasi kasir warung kopi. Pasang, atur, jalankan.\n\n- [Instalasi](docs/instalasi.md)\n- [Konfigurasi](docs/konfigurasi.md)\n' > README.md
printf '# Instalasi\n\n(Kerangka - akan dilengkapi.)\n' > docs/instalasi.md
printf '# Konfigurasi\n\n(Kerangka - akan dilengkapi.)\n' > docs/konfigurasi.md
printf '# CHANGELOG\n\n## 1.0.0 - 2026-11-30\n\n### Added\n\n- Kerangka panduan: README, instalasi, konfigurasi.\n' > CHANGELOG.md
printf '# Kontribusi Dokumen\n\n- Satu branch per topik, awali nama dengan docs/\n- Pesan commit memakai type docs\n- Perubahan besar dibicarakan dulu di issue\n' > CONTRIBUTING.md
git add .
git commit -m "docs: rintis panduan toko"
git init --bare ../panduan-toko.git
git remote add origin ../panduan-toko.git
git push -u origin main

Output yang Dihasilkan (git commit dan git push):

text
[main (root-commit) 1db72f5] docs: rintis panduan toko
 5 files changed, 24 insertions(+)
 create mode 100644 CHANGELOG.md
 create mode 100644 CONTRIBUTING.md
 create mode 100644 README.md
 create mode 100644 docs/instalasi.md
 create mode 100644 docs/konfigurasi.md

text
To ../panduan-toko.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

Empat artefak terpasang sekaligus dalam satu commit docs:. Siti mengambil salinannya:

bash
cd ..
git clone panduan-toko.git siti
git -C siti remote set-url origin ../panduan-toko.git
git -C siti config user.name "Siti Rahma"
git -C siti config user.email "[email protected]"

Pekerjaan Siti berangkat dari issue #4 — “panduan instalasi terlalu tipis, pembaca baru tersesat” — yang dilaporkan tim support. Satu branch per topik, dua bagian baru menggantikan kerangka:

bash
cd siti
git switch -c docs/panduan-instalasi
printf '# Instalasi\n\n## Persyaratan\n\n- Node.js 20 atau lebih baru\n- npm yang menyertainya\n\n## Langkah Instalasi\n\n1. Klon repository aplikasi.\n2. Jalankan `npm install`.\n3. Salin `.env.example` menjadi `.env`.\n' > docs/instalasi.md
git add docs/instalasi.md
git commit -m "docs: lengkapi panduan instalasi dengan persyaratan dan langkah"
git push -u origin docs/panduan-instalasi

Output yang Dihasilkan (git commit dan git push):

text

[docs/panduan-instalasi 99de246] docs: lengkapi panduan instalasi dengan persyaratan dan langkah
 1 file changed, 10 insertions(+), 1 deletion(-)

text
To ../panduan-toko.git
 * [new branch]      docs/panduan-instalasi -> docs/panduan-instalasi
branch 'docs/panduan-instalasi' set up to track 'origin/docs/panduan-instalasi'.

Di platform, Siti membuka pull request dari docs/panduan-instalasi menuju main dengan deskripsi “Menutup #4”. Repository ini sudah memuat empat issue sebelumnya, jadi pull request menyusul sebagai nomor #5 — dan deskripsi itu bukan hiasan: PR yang di-merge otomatis menutup issue yang dirujuknya, perilaku platform yang dibahas di Issues dan Discussions .

Budi menimbang sebagai editor. Review pertamanya menemukan satu lubang: persyaratan menyebut Node.js 20, tetapi pembaca baru tidak diberi cara memeriksa versinya. Siti menjawab dengan satu commit lagi di branch yang sama:

bash
printf '# Instalasi\n\n## Persyaratan\n\n- Node.js 20 atau lebih baru - periksa dengan `node --version`\n- npm yang menyertainya - periksa dengan `npm --version`\n\n## Langkah Instalasi\n\n1. Klon repository aplikasi.\n2. Jalankan `npm install`.\n3. Salin `.env.example` menjadi `.env`.\n' > docs/instalasi.md
git add docs/instalasi.md
git commit -m "docs: tambahkan cara memeriksa versi node dan npm"
git push

Output yang Dihasilkan (git commit dan git push):

text

[docs/panduan-instalasi 591afb8] docs: tambahkan cara memeriksa versi node dan npm
 1 file changed, 2 insertions(+), 2 deletion(-)

text

To ../panduan-toko.git
   99de246..591afb8  docs/panduan-instalasi -> docs/panduan-instalasi

Push inkremental masuk ke branch PR yang sama — halaman pull request menampilkan commit barunya tanpa perlu PR baru. Disetujui; penggabungan berjalan dari meja Budi:

bash
cd ../budi
git fetch origin
git merge --no-ff origin/docs/panduan-instalasi -m "Gabungkan panduan instalasi (#5)"
git push origin main
git push origin --delete docs/panduan-instalasi

Output yang Dihasilkan (merge, push main, dan penghapusan remote branch):

text
Merge made by the 'ort' strategy.
 docs/instalasi.md | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

text

To ../panduan-toko.git
   1db72f5..797dab9  main -> main

text

To ../panduan-toko.git
 - [deleted]         docs/panduan-instalasi

Terbitan ditutup dengan versi: CHANGELOG bertambah dan tag menandai titiknya:

bash
printf '# CHANGELOG\n\n## 1.1.0 - 2026-12-03\n\n### Added\n\n- Panduan instalasi lengkap: persyaratan dan langkah\n\n## 1.0.0 - 2026-11-30\n\n### Added\n\n- Kerangka panduan: README, instalasi, konfigurasi.\n' > CHANGELOG.md
git add CHANGELOG.md
git commit -m "docs: catat panduan 1.1.0 di CHANGELOG"
git tag -a v1.1.0 -m "Panduan 1.1.0"
git push origin main --tags

Output yang Dihasilkan (git commit dan git push):

text

[main 7e690db] docs: catat panduan 1.1.0 di CHANGELOG
 1 file changed, 6 insertions(+)

text
To ../panduan-toko.git
   797dab9..7e690db  main -> main
 * [new tag]         v1.1.0 -> v1.1.0

Keadaan akhirnya terbaca dari dua sisi:

bash

git log --oneline --decorate
git log --oneline -- docs/instalasi.md

Output yang Dihasilkan (dua perintah):

text
7e690db (HEAD -> main, tag: v1.1.0, origin/main) docs: catat panduan 1.1.0 di CHANGELOG
797dab9 Gabungkan panduan instalasi (#5)
591afb8 docs: tambahkan cara memeriksa versi node dan npm
99de246 docs: lengkapi panduan instalasi dengan persyaratan dan langkah
1db72f5 docs: rintis panduan toko

text
591afb8 docs: tambahkan cara memeriksa versi node dan npm
99de246 docs: lengkapi panduan instalasi dengan persyaratan dan langkah
1db72f5 docs: rintis panduan toko

Hash di mesin pembaca berbeda, bentuknya tidak: log penuh menampung gelembung merge (#5) sebagai satu unit kerja, sedangkan log terfilter per topik membaca seperti riwayat editorial — kapan panduan dirintis, dilengkapi, dikoreksi. Jalur pada keluaran menyesuaikan lokasi direktori. Siti menutup siklus dengan menarik hasil terbitan:

bash
cd ../siti
git switch main
git pull --ff-only

Output yang Dihasilkan (perintah terakhir):

text
From ../panduan-toko
   1db72f5..7e690db  main       -> origin/main
 * [new tag]         v1.1.0     -> v1.1.0
Updating 1db72f5..7e690db
Fast-forward
 CHANGELOG.md      |  6 ++++++
 docs/instalasi.md | 11 ++++++++++-
 2 files changed, 16 insertions(+), 1 deletion(-)

Tag ikut ditarik bersama main — setiap pembaca kini bisa memeriksa v1.1.0 dan mendapatkan dokumen persis seperti keadaan saat diterbitkan.

Umpan Balik Pembaca Lewat Issues #

Pembaca dokumen jarang membuka terminal Git — umpan balik mereka masuk lewat issues: “langkah ketiga gagal”, “contoh kedua kedaluwarsa”, “tambahkan panduan backup”. Issue adalah radar paling jujur untuk dokumentasi karena tiap laporan berasal dari pembaca nyata yang tersandung; triagenya pola Issues dan Discussions : beri label, tutup duplikat, ubah yang valid menjadi branch docs/… — jalur yang ditempuh issue #4 sampai ditutup otomatis oleh PR #5.

Delapan pola kini terkumpul: main-only untuk proyek sendirian, feature branch untuk isolasi fitur, hotfix untuk darurat, branch rilis untuk terbitan terjadwal, fork untuk kontributor asing, PR ringan untuk tim kecil, monorepo untuk banyak produk satu rumah, dan siklus editorial untuk repository kata-kata. Pertanyaan penutup section tinggal satu: dari delapan pola itu, mana yang tepat untuk proyek dan tim kita? Pertanyaan itu punya kerangka jawab — bukan selera — dan chapter berikutnya menyusun matriksnya.