Dokumentasi berapa tingkat yang Anda harapkan akan diberikan kepada Anda oleh pengembang?

Judul mengatakan itu semua benar-benar.

Kadang-kadang bisa berakhir bahwa pengembangan dan TI berselisih tentang hal semacam ini. Tingkat dokumentasi apa yang Anda harapkan ketika Anda diharapkan untuk menginstal, menambal, memelihara, memulai, menghentikan dan mendiagnosis solusi yang berjalan di satu atau lebih server?

Semua hal ini harus didokumentasikan secara rinci, meskipun ketika operasi standar untuk sistem operasi, server aplikasi, server web dll, Anda mungkin dapat mengasumsikan operasi TI yang orang tahu bagaimana melakukannya.

Instalasi: dokumentasikan segala sesuatu tentang cara diinstal dan dikonfigurasi, termasuk cara mengetahui apakah itu beroperasi dengan benar.

Ceritakan tentang arsitekturnya, terutama tentang komunikasi antara berbagai komponen solusi (mis. Rentang port - mekanisme RPC sering menggunakan berbagai port - kita perlu mengetahui apa jangkauannya dan kapan aplikasi mungkin kehabisan port).

Penambalan: mendokumentasikan segala sesuatu yang spesifik untuk aplikasi - apa yang perlu ditutup sebelum menambal, dan tindakan tindak lanjut apa pun setelah penambalan (cache, indeks, proxy yang mungkin perlu dibersihkan atau dibangun kembali).

Maintainance: dokumentasikan seperti apa operasi normal dan tidak normal - antrian apa dan hal-hal lain yang harus dipantau dan berapa kisaran normalnya.

Beri tahu kami cara mengelola data - terutama tabel dan file yang tumbuh tanpa batas (mis. File log dan riwayat transaksi). Bagaimana ini harus dibersihkan dan apa dampak dari menghapus entri lama? (pada pelaporan dll).

Beri tahu kami cara melakukan tindakan manajemen "bisnis seperti biasa" / in-life standar - ini mungkin menambah atau memodifikasi akun pengguna, misalnya.

Beri tahu kami tentang tindakan manajemen reguler apa pun yang mungkin diperlukan (mis. Sertifikat mana yang digunakan dan apa yang harus dilakukan ketika sudah kedaluwarsa).

Untuk semua perubahan, beri tahu kami cara mengembalikannya (tidak semua perubahan berhasil). Dan beri tahu kami bahwa Anda telah menguji paket rollback!

Diagnosis: Format dan file file log dokumen dan SETIAP pesan kesalahan aplikasi yang mungkin muncul, mengatakan apa artinya pesan kesalahan telah salah dan apa yang mungkin perlu diubah untuk memperbaikinya. Jangan pernah menggunakan pesan kesalahan yang sama untuk dua peristiwa berbeda.

Ditembak jatuh dan mulai naik: Bagaimana, urutan apa, prosedur khusus apa pun (mis. Membiarkan server menguras koneksi sebelum mematikannya).

Saya sangat tidak setuju bahwa cara terbaik untuk melakukan ini adalah dengan membuang aplikasi di pagar dan membiarkan orang-orang IT mengerjakan apa yang dibutuhkan. Dokumentasi operasional (dan secara umum, fitur pengelolaan aplikasi) perlu dipikirkan di muka.

Pertanyaan lanjutannya adalah: apa yang terjadi ketika (tidak jika) pengembang tidak menyediakan dokumentasi yang cukup?

Saya merekomendasikan bahwa TI memiliki kemampuan untuk memasukkan laporan cacat terhadap perangkat lunak, menggunakan sistem pelacakan cacat apa pun yang digunakan pengembang. Dengan begitu, jika mereka tidak memberi tahu Anda, misalnya, bahwa file-file dalam folder tertentu perlu dibersihkan, dan bahwa hanya nilai satu minggu yang harus disimpan, Anda dapat memasukkan cacat yang mengatakan "aplikasi mengisi disk dengan file log ", dan sarankan mereka bekerja dengan IT pada teknik terdokumentasi untuk membersihkan folder itu.

Daftar persyaratan untuk dokumentasi saya adalah (tidak dalam urutan tertentu):

(dokumentasi tentang :)

• semua saklar baris perintah
• semua status keluar dan mengembalikan nilai
• mencatat pesan (tidak terlalu banyak isinya tetapi menjelaskan bidang jika tidak dapat dikonfigurasi)
• sintaks konfigurasi
• mengaktifkan file konfigurasi
• penggunaan memori
• apakah itu di-threaded atau di-forked
• apa sinyal yang bereaksi pada server
  • apakah ada sinyal yang tidak me-restart server tetapi membuatnya membaca ulang konfigurasi
  • bagaimana perilakunya? (Apakah menunggu utas / proses yang ada untuk menyelesaikan dengan konfigurasi lama. Apakah itu membunuhnya, ...)
• apa yang terjadi pada shutdown najis (terutama jika itu semacam layanan / server kegigihan)
• apakah itu log melalui sistem yang disediakan panggilan atau apakah itu log dengan sesuatu yang ditulis dengan sendirinya ( yuck untuk apache dan akses log - Saya jelas lebih suka alat on-board untuk logging)
• IPv4 dan IPv6 siap jika itu layanan jaringan
• dokumentasi pada trunk dan dokumentasi pada versi tertentu
  • tidak ada yang seburuk mengkonfigurasi sesuatu selama berjam-jam hanya untuk mengetahuinya akan diabaikan karena opsi konfigurasi hanya tersedia di bagasi
• opsi konfigurasi mana yang valid di versi mana (tersedia sejak: v1.0, tidak digunakan lagi karena: v1.2 atau yang serupa)

Dokumentasi seperti ini adalah contoh untuk dokumentasi yang baik:

• http://httpd.apache.org/docs/2.2/
• http://www.postgresql.org/docs/8.3/static/index.html

Saya menganggap dokumentasi seperti ini penuh kegagalan:

• http://tomcat.apache.org/tomcat-6.0-doc/index.html

Juga FreeBSD Handbook adalah contoh dokumentasi yang bagus, dan pendekatan OpenBSD. Mereka menendang hal-hal yang tidak didokumentasikan dengan baik.

EDIT: daftar ini sama sekali tidak lengkap itu hanya hal-hal dasar yang langsung muncul di benak saya. Juga dokumentasi harus dapat dibaca dengan baik, bukan hanya sesuatu yang berbunyi seperti seseorang yang muntah .

Singkatnya, saya mengharapkan dokumentasi yang saya tentukan dan kontrakkan.

Terlalu sering detail kritis ini diabaikan begitu saja. Pengguna akhir mengharapkannya dan menginginkannya gratis tentu saja. Pengembang yang baik akan memperbaiki pengawasan ini di awal proses dan menetapkan harapan termasuk harga dan persyaratan waktu.

Saya percaya TI perlu berkomunikasi dengan pengembang seperti apa dokumentasi yang dibutuhkan. Cara terbaik untuk melakukan ini adalah jika pengembangan memberikan versi pra-rilis (atau rilis iterasi) dari solusi untuk dimainkan dan diuji oleh TI sehingga TI dapat merespons dengan apa yang dibutuhkan.

Membuat catatan rilis yang memadai dengan aplikasi akan menjadi awal yang baik. Jika ada perubahan pada perilaku saat ini dengan rilis, setiap catatan dari QA tentang perubahan pada dependensi atau perilaku mulai / berhenti, perubahan beban ke server atau database yang bergantung, dll.

@Spoike (saya belum bisa mengomentari jawaban ..)

Pelaksana TI (perannya akan bervariasi berdasarkan jenis dan ukuran perusahaan) harus bekerja secara konsisten untuk mencapai yang berikut:

• Instal / turnover Persyaratan Minimum - dengan kata lain, TI tidak bisa pasif dan mengharapkan pengembang untuk "tahu" informasi apa yang diperlukan pada waktu install / turnover. Saya telah menemukan bahwa sering ada banyak kebingungan / ketidaksepakatan dalam TI tentang apa yang merupakan dokumentasi yang tepat dari suatu aplikasi. Dev memahami persyaratan (kami harap) dan IT harus kaukus untuk menemukan apa - minimal - yang diperlukan.

• Prosedur instal / turnover - di pengaturan perusahaan Anda mungkin menyebutnya Kontrol Perubahan atau Tata Kelola, tetapi pada dasarnya ini adalah siklus tinjauan standar di mana IT duduk dengan instal atas Dev PRIOR untuk mendapatkan pengarahan tentang produk dan kebutuhannya.

Menginstal aplikasi tidak seperti memulai debut produksi teater. Sebelum tirai naik, direktur (pengembang utama) bertemu berulang kali dengan tim tahap produksi (pelaksana TI) untuk memastikan semuanya "hanya begitu" untuk malam pembukaan (instalasi publik).

Anda tidak dapat mengubah persona Dev (mengapa Anda mau?), Tetapi Anda dapat mengarahkan ke tujuan bersama Anda dari aplikasi fantastis yang berjalan sangat cepat untuk semua pengguna. Konsensus Anda Persyaratan dokumen TI hanyalah salah satu hal yang diperlukan untuk memastikan hal itu.