Dokumentasi
DOKUMENTASI
Dokumentasi Foundation bukan brosur dengan manual tempelan. Ia pengetahuan operasional atas perangkat lunaknya, diterbitkan di repositori yang sama dengan kode yang dijelaskannya — sehingga ia tidak dapat menyimpang jauh dari apa yang dijelaskan, dan tetap tersedia bagi Anda apa pun yang terjadi kemudian.
Semua yang diterbitkan di sini bersifat publik
Anda dapat membaca seluruhnya sebelum memutuskan apakah Foundation cocok untuk proyek Anda, dan Anda dapat mengikutinya sendiri, sesuai kecepatan Anda, tanpa akun dan tanpa perlu berbicara dengan siapa pun. Tidak ada bagian yang terkunci, dan tidak ada versi khusus pelanggan.
Itu bagian yang disengaja dari cara proyek ini dibangun. Sebuah platform baru benar-benar dapat dipakai ulang bila pengetahuan untuk mengadopsi, mengatur, menerapkan, dan menjaga kemutakhirannya menyertai perangkat lunaknya, bukan tetap berada pada orang yang menulisnya.
Manual operasi
Delapan manual, masing-masing menjadi acuan bagi pokok bahasannya sendiri. Semuanya ditulis untuk orang yang belum pernah melihat Foundation.
- Adoption — membuat proyek Foundation baru
Bagaimana proyek baru dibentuk dari rilis Foundation yang tetap, sehingga ia dimulai bersama platform dan pengetahuan operasinya sekaligus.
- Deployment — menerbitkan situs yang sudah tervalidasi
Alur kerja dan pemeriksaan penting sebelum situs mengudara, termasuk pekerjaan domain dan DNS yang hanya dapat dilakukan pemilik akunnya.
- Foundation Upgrade — menyerap rilis yang lebih baru
Cara mengadopsi rilis Foundation yang lebih baru, dan bagaimana pemisahan berkas milik platform serta milik pemakai melindungi konfigurasi, konten, aset, dan merek Anda.
- Site customization — menyesuaikan situs
Panduan bagi pemakai hilir: apa yang perlu diubah, bagaimana menambahkan bahasa, dan di mana identitas situs sebenarnya berada.
- Branding and assets — merek dan aset visual
Peran aset yang digantikan situs dengan karya sendiri, dan bagaimana masing-masing ditukar tanpa mengubah platform.
- Content management — mengelola konten
Bagaimana halaman, navigasi, dan teks situs disimpan sebagai berkas, dan cara menambah atau mengubahnya.
- Validation — gerbang validasi
Apa yang diperiksa gerbang validasi sebelum sebuah perubahan diterima, dan bagaimana menjalankannya sendiri.
- Troubleshooting — penyelesaian masalah
Langkah awal ketika sesuatu tidak berjalan: dari keluaran penerapan sampai halaman yang tidak muncul sebagaimana mestinya.
Mengikutinya tidak perlu akun dan tidak perlu izin
Manual-manual itu ditulis untuk dibaca dan dijalankan oleh siapa pun. Tidak ada pendaftaran, tidak ada langganan, dan tidak ada bagian yang hanya dibuka setelah berbicara dengan Provelopment. Satu hal yang memang tidak dapat dilakukan dokumentasi: mengambil alih pekerjaan yang memerlukan akses akun — misalnya pengaturan DNS — karena itu tetap harus dilakukan pemilik akunnya.
Mulai dari mana
Urutan yang paling sedikit membuang waktu. Setiap langkah menyebut dokumen yang membahasnya.
Baca apa itu Foundation
README repositori: apa yang platform sediakan, apa yang sengaja tidak disertakan, dan seperti apa situs yang dibangun di atasnya.
Lihat ia berjalan sebelum membaca lebih banyak
Jalankan secara lokal, lalu telusuri situs dasarnya. Satu jam memakainya menjawab lebih banyak pertanyaan daripada sehari membaca spesifikasi.
Tentukan bagaimana Anda akan memegangnya
Satu situs atau beberapa, akun Anda sendiri atau pengaturan terkelola. Keputusan ini menentukan bagian-bagian lainnya lebih banyak daripada pilihan teknis mana pun.
Bentuk proyek Anda sendiri
Manual Adoption: membuat proyek dari sebuah rilis Foundation, sehingga Anda memulai bersama platform dan pengetahuan operasinya.
Jadikan benar-benar milik Anda
Site customization serta branding and assets: identitas, konten, bahasa, dan karya visual — semuanya melalui konfigurasi dan berkas, bukan dengan mengubah platform.
Terapkan di domain Anda sendiri
Manual Deployment dan panduan peluncuran, termasuk pekerjaan DNS yang hanya dapat dilakukan pemilik domain.
Jaga agar tetap mutakhir
Manual Foundation Upgrade ketika rilis baru layak diadopsi, dan manual Validation untuk mengetahui apa yang sebenarnya dibuktikan oleh gerbang validasinya.
Apa yang diasumsikan manual, dan apa yang tidak
Manual-manual ini ditulis untuk pengembang yang cakap tetapi belum pernah melihat Foundation. Mereka mengasumsikan Anda dapat memakai terminal, menjalankan pengelola paket, menyunting berkas, dan menerapkan aplikasi web pada penyedia tertentu. Mereka tidak mengasumsikan Anda pernah menulis kerangka kerja, dan tidak mengasumsikan Anda akan membaca seluruh dokumen arsitektur sebelum melakukan apa pun.
Mereka juga mengasumsikan pekerjaannya memang Anda sendiri yang mengerjakan. Setiap prosedur ditulis untuk seseorang yang bekerja di dalam salinan repositori miliknya, dengan akun hosting dan domainnya sendiri. Bila sebuah langkah hanya dapat diselesaikan dengan sesuatu yang hanya dapat diberikan pemilik akun — misalnya akses ke pengaturan DNS di registrar — manualnya menyebutkan hal itu pada saat itu juga, bukan membiarkannya ditemukan kemudian.
Yang tidak dilakukan manual adalah mengambil keputusan untuk Anda. Ia menjelaskan pilihan yang didukung platform beserta akibat masing-masing; ia tidak menentukan penyedia hosting mana yang harus dipakai, berapa bahasa yang sebaiknya diterbitkan, atau apakah situsnya Anda operasikan sendiri. Itu keputusan tentang usaha Anda, dan tugas dokumentasi adalah membuatnya menjadi keputusan yang berdasar alih-alih keputusan yang terjadi secara kebetulan.
Satu batas lain perlu dinyatakan terus terang, karena mudah diandaikan sebaliknya. Manualnya menjelaskan perilaku platform dan tanggung jawab pemakainya. Ia tidak dapat menjelaskan cara kerja internal layanan pihak ketiga yang dihubungkan sebuah situs, dan memang tidak mengklaim hal itu: bila sebuah titik integrasi menunjuk pada produk orang lain, dokumentasi produk itulah yang berlaku.
Dokumen di tingkat teratas repositori
Lima berkas yang menjelaskan produknya sendiri, bukan sebuah prosedur.