Mengomentari perkakas.
Kami sudah mencoba wiki online tetapi menemukan sejumlah batasan, yang mungkin sesuai selera pribadi, tetapi termasuk struktur dokumen dan yang paling penting harus terhubung ke server dokumentasi.
Terkoneksi adalah masalah serius jika Anda offline atau onsite (jelas Anda dapat mengurangi onsite dengan koneksi SSL aman dan lain-lain.)
Proses dokumentasi kami saat ini adalah:
- generator html statis
- sintaks penurunan harga
- sistem versi terdistribusi
Kami memiliki tata letak 'formal' untuk dokumentasi dan yang menyediakan struktur untuk menu (dan CSS terkait untuk penataan visual dll.)
Generator HTML Statis
Kami menggunakan generator html statis in-house berdasarkan cubictemp dan sejumlah alat lain: pygments , docutils .
Halaman yang dihasilkan (tidak?) Jelas terlihat jelek, karena sebagian besar dari kita / sysadmin / programmer kita tahu apa yang indah secara estetika tetapi memiliki total kurangnya koordinasi dalam membangun seperti itu.
Tapi itu memberi / mari kita sertakan file konfigurasi, skrip sampel, pdf, dll, tanpa harus khawatir tentang format html mengacaukannya atau khawatir tentang di mana menemukannya di 'server' untuk mengunduh.
Jika bukan HTML, cukup taruh di folder dan tambahkan tautan url ke sana.
HTML menyediakan struktur 'potensial' untuk tata letak, dan juga secara kritis menyediakan 'tautan' antara item pengetahuan / konten (serta mekanisme struktur dasar, seperti mampu membuat menu, daftar isi, dll.) Dengan HTML, setiap pengguna kini dapat menjalankan server web kecil di mesin mereka apakah lighttpd atau sesuatu yang kecil atau hanya penuh dengan Apache atau IIS.
Semua mesin kami memiliki gerutuan untuk melayani html dasar, dan bekerja cukup baik untuk kami.
Sintaks MARKDOWN.
Kami menggunakan MARKDOWN, Textish, atau atau reStructuredTEXT versi bastardised untuk membiarkan jus 'kreatif' kami menulis dokumentasi tanpa harus khawatir tentang HTML.
Ini juga berarti setiap orang dapat menggunakan editor favorit mereka (saya menggunakan Scintilla pada Windows dan * Nix) sementara yang lain di sini menggunakan vi / vim.
Sistem Versi Terdistribusi.
Kami menggunakan Git untuk 'mendistribusikan' dokumentasi antara pengguna. Oh, dan kami menggunakan kapasitas versinya juga.
Keuntungan utama bagi kami adalah bahwa kita semua dapat bekerja memperbarui dokumentasi tanpa harus terhubung ke server, dan tanpa harus menerbitkan karya 'selesai'. Kita semua dapat mengerjakan bagian yang sama dari dokumentasi, atau bagian yang berbeda, atau hanya mengkonsumsi informasi.
Secara pribadi, saya benci diikat ke server untuk memperbarui blog apalagi wiki. Git bekerja dengan baik untuk kita.
Mengomentari Alur Kerja
Wiki tampaknya menjadi "mode" untuk penyebaran / kodifikasi pengetahuan, tetapi seperti dikomentari di tempat lain semua proses menjadi sulit untuk dipertahankan, dan menemukan campuran alat yang paling mendukung kebutuhan tim Anda dan berkelanjutan akan membutuhkan waktu.
Solusi yang lebih baik akhirnya ditemukan dan tidak diamanatkan.