Orang-orang hebat yang membentuk Canonical memiliki satu tujuan: kami ingin menjadi perusahaan open source terbaik di dunia.
Saya pikir itu adalah tujuan yang didukung oleh manajemen kami, tetapi itu tidak menghilangkan fakta bahwa setiap orang yang bekerja di sini mungkin ingin membuat dunia menjadi tempat yang lebih baik, mungkin melalui perangkat lunak sumber terbuka. dalam darah kita
Saya benar-benar di sini karena saya ingin menulis dokumen yang bagus. Sejujurnya, penulis teknis terkadang memiliki tingkat keunggulan yang relatif rendah. Saya sangat senang ketika seseorang menemukan kesalahan kecil dalam contoh kode yang tidak jelas di akhir artikel yang panjang. Itu berarti mereka membacanya, dan itu sering kali menjadi ukuran utama keberhasilan dokumentasi. Tapi ini bukan kriteria utama bagi saya.
Apakah saya memperhatikan Anda?
Kami memiliki banyak inisiatif di Canonical saat kami tumbuh dan itu luar biasa. Di ranah doc, kami memiliki panduan Diátaxis untuk membantu kami mengatur pemikiran dan tulisan kami. Dalam tim pengembangan, kami memiliki berbagai komponen open source yang tidak kami tulis dan bukan milik kami – dan itu sangat berharga, karena begitulah cara open source dilakukan. Dan di organisasi lapangan kami dan dalam pekerjaan advokasi pengembang saya sendiri, kami berinteraksi dengan pengguna dan pengembang yang memberi kami umpan balik yang cepat, bermanfaat, dan konstruktif.
Sekarang, inilah saya, mencoba menggabungkan harta karun bimbingan itu sambil membuat dokumen yang benar-benar membantu pembaca kami. Pada pandangan pertama, ini mungkin tampak seperti tugas, tetapi pada kenyataannya, ini adalah tempat yang sangat menakjubkan. Dan di sinilah saya membutuhkan bantuan Anda, pembaca yang budiman.
Sebagai penulis teknis, saya selalu merasa bahwa itu adalah tanggung jawab utama saya Untuk menahan perhatian pembaca saya cukup lama untuk mengajari mereka sesuatu. Seni, tentu saja, tetap menjadi subjek. Teman saya Jack mengatakannya seperti ini: “Untuk benar-benar menjelaskan cara membuat kue, pertama-tama Anda harus menciptakan dunia.” Pembaca saya tidak datang untuk pelajaran fisika, tetapi mengukur di mana mereka duduk pada spektrum pengetahuan yang relevan terkadang bisa jadi menantang. Dan saya ingin semua orang mendapatkan apa yang mereka butuhkan.
Definisi “dokumen pengasih”
Di sinilah saya membutuhkan bantuan Anda, pembaca. Saya mencoba mengintegrasikan umpan balik luar biasa berikut ke dalam pendekatan dokumentasi yang lebih baik. Ketahuilah bahwa saya mengompresi umpan balik ini dan menambahkan pengalaman indrawi saya sendiri, tetapi tidak dengan cara yang mendistorsi pesan aslinya:
- Dokumen tidak cukup narasi. Dulu seperti itu, tetapi menjadi terlalu steril dan manis.
- Kami mengemas beberapa produk open source, dan beberapa di antaranya memiliki dokumentasi yang buruk/terbatas/tidak lengkap. Kami memilih produk itu, jadi kami harus bertanggung jawab.
- MAAS mencakup banyak pembelajaran sampingan (misalnya, jaringan, BMC, dan gambar sistem operasi pengemasan untuk penyebaran). Tidak ada tempat untuk mempelajari semuanya.
- Beberapa pengguna dan pengembang MAAS kami tidak cukup siap untuk tingkat pengetahuan yang diperlukan untuk kesuksesan MAAS, bukan karena kesalahan mereka sendiri. Mungkin mereka mewarisi produk, atau didorong ke pekerjaan karena ketersediaan, atau orang yang paling berpengetahuan di organisasi mereka.
Tim MAAS membahas masalah ini dalam forum terbuka hari ini. Yang sangat penting bagi kami dalam hal ini adalah kalimat ini:Perusahaan sumber terbuka terbaikMenjadi yang terbaik berarti memilih posisi budaya FOSS mana yang akan diadopsi dan mana yang harus ditolak.
Sejak awal 90-an, saya telah bekerja dengan berbagai proyek open source, sering melakukan beberapa bentuk dokumentasi. Kadang-kadang, saya merasa tidak nyaman bekerja dengan (atau terus bekerja dengan) tim sumber terbuka karena beberapa sikap umum terhadap pengguna akhir:
- “Jika pengguna tidak memahami teknologi yang mendasarinya, kami toh tidak membutuhkannya.”
- “Hal-hal ini tidak sempurna. Anda harus mencari tahu, Google adalah teman Anda. Semoga berhasil.”
- “Aku bukan guru SMAmu.”
- tidakkah kamu mengerti? Ini sangat menyedihkan untukmu.”
- “Ini dia. Jika Anda bisa menggunakannya, bagus, jika tidak, ya sudahlah.”
Masalah di sini dapat diringkas sebagai berikut:Pengguna bukan masalah sayaAtau, untuk lebih spesifik dengan situasi saya, saya benci gagasan bahwa “memahami pengguna bukanlah masalah saya”.
Saya tidak berlangganan. Menjadi perusahaan open source terbaik di dunia berarti memiliki belas kasih bagi pengguna. Menulis dokumentasi open source terbaik berarti memiliki belas kasih atas pemahaman pengguna: pemahaman kami Produk; pemahaman tentang Paket perangkat lunak FOSS kami; dan pemahaman tentang Prinsip dasar Hal ini diperlukan untuk keberhasilan aplikasi dan penggunaan produk. Inilah yang saya sebut “dokumentasi penuh kasih”.
Apa tanggung jawab kita?
Ide ini, tentu saja, membuka pertanyaan tentang tanggung jawab—khususnya tanggung jawab atas produk dan ide orang lain. Kami sudah terbiasa mengambil peran sebagai pelaku untuk produk-produk yang kami kemas yang menjadi yatim piatu oleh produsennya. Ini adalah pembangunan yang bertanggung jawab. Tetapi ada masalah yang lebih besar ketika kami mencoba mengambil tanggung jawab untuk mendokumentasikan produk aktif orang lain atau bahkan mengajari pengguna kami dasar-dasarnya.
Masalah sulit ini melibatkan dua hal yang sangat dihormati di komunitas open source: kepemilikan Dan Seni sebelumnya.
Kepemilikan berarti kita harus berhati-hati agar tidak menyalip pencipta aslinya. Jika mereka memiliki dokumentasi, dan dokumentasi tersebut kurang sehingga mempengaruhi produk kami, kami bertanggung jawab untuk menjelaskan semuanya dengan jelas. Namun, untuk menghormati, kami tidak memiliki hak atau tanggung jawab untuk menulis ulang dokumentasi orang lain – terutama untuk kenyamanan pembaca atau alur naratif.
Seni sebelumnya pada dasarnya berarti bahwa ada banyak orang yang semuanya lebih pintar dari kita dan telah menjelaskan prinsip-prinsip di balik teknologi dasar kita. Seni sebelumnya memang merupakan landasan mutlak FOSS: kami menghormati pekerjaan Anda, menghargai Anda, dan menghormati Anda sebagai pencipta. Memperluas ini ke penulisan teknis, ini berarti menghormati penulis yang telah datang sebelumnya, bahkan jika buku mereka tidak dilisensikan di bawah lisensi sumber terbuka.
Kami benar-benar harus mengarahkan Anda ke sumber daya yang tersedia, bahkan mungkin mengidentifikasi konten yang spesifik dan relevan. Mencoba untuk mengulang atau meringkas materi yang telah (seringkali indah) dijelaskan adalah hal yang biasa di Internet, tetapi tidak menunjukkan rasa hormat yang tepat untuk sumber yang ada.
Permintaan ide
Kami memiliki beberapa ide untuk bibit, tetapi kami ingin membaginya dengan Anda, pembaca yang budiman, dan mendapatkan komentar dan saran Anda. Berikut adalah sorotannya:
- Kami ingin melakukan apa pun untuk mendapatkan perhatian Anda sambil membantu Anda mempelajari apa yang perlu Anda ketahui. Kami tidak dapat sepenuhnya menyesuaikan pengalaman itu untuk setiap pembaca, tetapi kami selalu dapat meningkatkannya.
- Kami ingin bertanggung jawab atas penjelasan teknis terkait yang tidak dapat diselesaikan dengan jelas oleh sumber lain. Jika kami menggunakan PostgreSQL dengan cara khusus atau unik, kami akan mendokumentasikan semua yang mungkin membingungkan atau tidak jelas hanya dengan membaca dokumentasi PostgreSQL.
- Kami ingin bertanggung jawab atas dokumentasi apa pun yang unik untuk produk kami, dan kami mencoba memastikan bahwa dokumentasi itu terfokus, lengkap, dan dapat dimengerti.
- Kami ingin memoderasi penggunaan ide dokumen terstruktur kami, seperti diátaxis, templat halaman, dan alat navigasi—dan memoderasi penggunaannya untuk memungkinkan narasi mengalir dan kebutuhan Anda untuk mengubah konteks saat mencoba Belajar atau melakukan pekerjaan berkurang. sesuatu
- Kami ingin bertanggung jawab untuk membantu Anda menggunakan dokumen kepemilikan dan karya sebelumnya secara lebih efektif untuk memajukan Anda baik dalam pengetahuan maupun pemahaman di bidang yang terkait langsung dengan MAAS.
- Kami ingin melakukan Semua Dari sini dengan cara yang menawarkan rasa hormat yang pantas bagi mereka yang telah pergi. Ini adalah semangat FOSS.
Kami akan senang untuk memiliki tanggapan Anda. Kami telah memikirkan hal ini, tetapi pada akhirnya, tujuan kami adalah untuk dapat menulis dokumen yang menarik perhatian Anda dengan benar dan memberi Anda informasi yang Anda butuhkan dengan cara yang paling tepat.
Tolong beritahu kami apa yang Anda pikirkan. Kami sangat ingin tahu.
