Belajar Backstage - TechDocs Dasar

#Pendahuluan

Di episode 6, kalian membangun golden path dengan Scaffolder — komponen baru lahir lengkap dengan struktur, repository, dan entri catalog. Episode 7 melengkapi komponen itu dengan sesuatu yang sering dianggap nomor dua: dokumentasi. Kita masuk ke TechDocs — cara Backstage memperlakukan dokumentasi sebagai bagian dari alur kerja, bukan lampiran yang mudah basi. Tujuannya sederhana: setiap engineer membuka halaman komponen di Backstage, dan di sana sudah ada dokumentasi yang akurat, selalu sinkron dengan versi kode yang sedang berjalan.

#Konsep Docs-as-Code

Dokumentasi yang baik sering gagal bukan karena isinya, melainkan karena prosesnya: ditulis di Google Docs, versinya mengambang, dan tanggal rilisnya tidak pernah jelas. Docs-as-code menyelesaikan ini dengan memperlakukan dokumentasi persis seperti kode:

• Ditulis dalam format teks biasa (Markdown) di dalam repository.
• Versinya mengikuti versi kode — dokumentasi yang menyertai sebuah rilis menjelaskan rilis itu.
• Di-review lewat pull request, bukan lewat komentar di dokumen terpisah.
• Dibangun oleh CI dan diterbitkan secara otomatis.

TechDocs membawa model ini ke tingkat berikutnya: halaman dokumentasi tampil di dalam Backstage sendiri, pada halaman yang sama dengan entity komponen yang bersangkutan. Kalian tidak perlu mengunjungi wiki eksternal — dokumentasinya ada di tempat kerja kalian.

#MkDocs dan techdocs-core

#Generator Dokumentasi

TechDocs memakai MkDocs sebagai generator: ia membaca file Markdown dan menghasilkan situs statis yang cepat. Kuncinya ada pada plugin techdocs-core — satu paket ekstensi yang disediakan Backstage untuk menambah komponen dokumentasi seperti tab, code block dengan bahasa tertentu, dan integrasi tema MkDocs Material. Konfigurasi MkDocs diletakkan di file mkdocs.yml di akar repository.

site_name: 'payment-api-docs'
docs_dir: docs
plugins:
  - techdocs-core
nav:
  - Overview: index.md
  - Getting Started: getting-started.md
  - API: api.md
markdown_extensions:
  - mkdocs-awesome-pages-plugin.v2
  - mkdocs-monorepo-plugin

docs_dir menunjuk ke folder docs, plugins memuat techdocs-core, dan nav menyusun menu navigasi. techdocs-core menggabungkan beberapa plugin MkDocs dalam satu paket sehingga kalian cukup menyebutnya sekali tanpa mengelola selusin plugin satu per satu.

#Struktur Folder docs

#Satu Folder, Banyak Markdown

Dokumentasi disimpan di folder docs/ di dalam repository, berisi file Markdown. TechDocs mendukung sintaks Markdown standar, dan dengan techdocs-core kalian juga bisa memakai fitur lanjutan seperti tab dan diagram. Struktur yang rapi biasanya terlihat seperti ini:

docs/
  index.md
  getting-started.md
  api.md
  images/
    architecture.png
mkdocs.yml

Halaman pertama biasanya docs/index.md, dan urutan menu ditentukan oleh nav di mkdocs.yml. Gambar disimpan dalam subfolder docs/images agar ikut ter-build. Jangan letakkan gambar di luar docs_dir — MkDocs hanya memproses file yang berada di dalam folder itu.

#Menandai dengan Anotasi

Agar TechDocs tahu bahwa sebuah repository berisi dokumentasi, tambahkan anotasi backstage.io/techdocs-ref pada entity di catalog-info.yaml. Nilainya menunjuk ke lokasi file mkdocs.yml, biasanya direktori itu sendiri.

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-api
  annotations:
    backstage.io/techdocs-ref: dir:.
spec:
  type: service
  owner: group:platform-team

Nilai dir:. berarti dokumentasi berada di akar repository. Tanpa anotasi ini, tab TechDocs di halaman komponen tidak akan menemukan apa pun, dan build dokumentasi tidak akan terhubung ke entity yang benar.

#Build dan Serve

#Generate dan Preview Lokal

Untuk melihat hasil secara lokal, gunakan techdocs-cli (paket @techdocs/cli). Perintah generate menjalankan MkDocs dan menghasilkan situs statis, sedangkan serve menampilkannya untuk pratinjau interaktif di browser.

npx @techdocs/cli generate
npx @techdocs/cli serve

generate membaca docs/ dan mkdocs.yml, lalu menghasilkan folder dokumentasi statis di dalam repository. serve membuka pratinjau interaktif di browser. Keduanya wajib dijalankan di direktori repository yang memuat mkdocs.yml — di luar itu, cli akan gagal menemukan konfigurasi.

#Local Preview vs Cloud Storage

Pratinjau lokal hanya untuk pengembangan. Di lingkungan sungguhan, hasil generate di-publish ke storage jarak jauh, dan backend TechDocs mengambilnya dari sana setiap kali user membuka halaman dokumentasi. Tiga penyedia paling umum adalah S3, Google Cloud Storage, dan Azure Blob Storage.

#Mengonfigurasi Publisher

Cloud storage disambungkan lewat konfigurasi techdocs.publisher di app-config.yaml. Nilai techdocs.publisher.type menentukan penyedia: awsS3 untuk S3, googleGcs untuk Google Cloud Storage, dan azureBlobStorage untuk Azure Blob. Setiap jenis punya pengaturan bucket atau container sendiri.

techdocs:
  builder: 'external'
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: 'backstage-techdocs'
      region: 'ap-southeast-1'
      s3ForcePathStyle: false

Nilai builder: 'external' menandakan bahwa build tidak dilakukan oleh backend TechDocs, melainkan oleh CI — hasilnya lalu di-publish ke S3. Ini pola yang paling umum di produksi: CI membangun dokumentasi di setiap merge, kemudian mengunggah hasilnya.

#Publish ke Cloud

Setelah backend diarahkan ke penyedia, perintah publish mengirim hasil build ke storage. Dari CI, perintah ini dijalankan dengan parameter yang sesuai penyedia:

npx @techdocs/cli publish --publisher-type awsS3 --storage-name backstage-techdocs

Dengan pola ini alur docs-as-code menutup lingkarannya: developer menulis Markdown di docs/, pull request di-review, CI menjalankan generate lalu publish, dan halaman TechDocs di Backstage langsung menampilkan versi terbaru.

#Penutup

Pada episode 7 ini, kalian menghidupkan dokumentasi dengan TechDocs: konsep docs-as-code, generator MkDocs dengan plugin techdocs-core, konfigurasi mkdocs.yml, struktur folder docs/, anotasi backstage.io/techdocs-ref pada entity, perintah generate dan publish dari @techdocs/cli, serta perbedaan pratinjau lokal dengan storage cloud seperti S3, GCS, dan Azure Blob.

Inti yang harus dibawa pulang:

• Docs-as-code berarti dokumentasi ber-versi bersama kode — ditulis di repository, direview lewat pull request, dan dibangun oleh CI.
• techdocs-core adalah satu-satunya plugin yang wajib — ia membawa sebagian besar fitur MkDocs yang dibutuhkan TechDocs.
• Anotasi menentukan koneksi — tanpa backstage.io/techdocs-ref, TechDocs tidak tahu di mana mencari dokumentasi sebuah entity.
• Cloud storage adalah jawaban produksi — pilih S3, GCS, atau Azure Blob sesuai infrastruktur, dan biarkan CI yang mem-publish.

Di episode 8 berikutnya, kita mengunci pintu Backstage: Authentication & Identity — bagaimana Backstage mengenali user, menghubungkan berbagai penyedia login seperti GitHub, Google, OIDC, dan SAML, serta bagaimana identitas itu mengalir sampai ke backend.