Saya telah menyelesaikan aplikasi web yang pada dasarnya dikembangkan dalam PHP dan hanyalah aplikasi web biasa. Biasanya ketika saya memberikan rilis produksi akhir saya hanya menyerahkan dokumentasi kode dan informasi arsitektur kepada klien. Namun, untuk proyek khusus ini klien bersikeras memiliki data masuk dan keluar yang lengkap tentang proyek.

Jadi saya hanya ingin tahu ... Apa saja dokumen teknis dan non-teknis wajib yang dapat saya berikan kepada klien saya terpisah dari dokumentasi kode dan arsitektur?

(Juga akan agak keren untuk menghubungi klien tentang berbagai statistik dan data tentang proyek sehingga ia benar-benar mengetahui jumlah pekerjaan yang terlibat dan seberapa keren sebenarnya produk tersebut.)

Saya pikir daftarnya harus mencakup:

• Persyaratan non-teknis (ada dokumen seperti itu, kan?)
• Persyaratan teknis
• Dokumen "keputusan" (jika ada) yang menjelaskan mengapa beberapa keputusan dibuat atas yang lain. Ini mungkin sudah dalam persyaratan atau dokumen arsitektur yang berbeda, tetapi kami biasanya melakukan ini secara terpisah untuk Keputusan Besar.
• Kode dan sumber daya lainnya (file gambar, CSS, dll ...)
• Model basis data (seperti diagram, dokumen, apa pun)
• DDL untuk membuat database.
• DML untuk seed database.
• Dokumen yang menjelaskan pengaturan aplikasi dan pemotretan masalah dasar.
• Daftar nama pengguna penting dan kata sandi (untuk akun Admin), serta petunjuk tentang cara mengubah kata sandi. Idealnya, ketika mereka membuat situs web untuk pertama kalinya, mereka harus diminta memasukkan kata sandi admin baru, tetapi ini lebih merupakan masalah arsitektur.
• Persyaratan sistem, dan untuk aplikasi web, persyaratan hosting minimum juga (Apakah aplikasi memerlukan MySQL atau PostgreSQL? Berapa banyak RAM ?, dll ...)

Tidak semua hal ini mungkin tersedia (atau perlu) untuk setiap proyek, tetapi saya pikir ini adalah panduan umum yang baik.

Selain jawaban FrustratedWithFormsDesigner yang sangat bagus, saya ingin mengatakan apa saja yang termasuk dalam dokumen non teknis (seperti yang kami lakukan):

• data analisis: apa yang pelanggan katakan ketika Anda pertama kali berbicara tentang persyaratan?

• penawaran yang Anda buat:

  • dokumen persyaratan produk
  • dan dokumen spesifikasi fungsional

  yang bersama-sama bertindak sebagai semacam kontrak tentang apa yang harus Anda lakukan dan apa yang Anda harapkan
  pelanggan berikan selama pengembangan serta perkiraan waktu dan biaya.

• spesifikasi termasuk protokol peninjauan, penggunaan dan rencana uji, hasil pengujian

• desain di UML dan semua dokumen terkait

• dokumentasi kode sumber (doxygen atau apa pun)

• panduan manual dan instalasi

• jumlah aktual aktual sumber daya (waktu dan uang) yang digunakan untuk proyek, sehingga Anda dapat menulis faktur

• beberapa pelanggan menginginkan protokol rapat, yang kemudian merupakan perpanjangan dari "dokumen keputusan" yang disebutkan di atas

Semoga itu yang Anda cari.

Ikuti dokumentasi mana pun yang berlaku untuk proyek Anda dari yang berikut ini. Anda mungkin sudah memilikinya.

Dokumentasi teknis:

• Detail tentang PHP dan informasi tentang bagaimana hal itu berguna untuk proyek
• Rincian tentang ujung belakang dan informasi tentang bagaimana itu berguna untuk proyek
• Informasi tentang konektivitas Database beserta gambar-gambar yang cocok menggambarkan aliran data
• Informasi tentang bahasa pemrograman lain atau aplikasi yang terlibat dalam proyek seperti XML, HTML dll.
• File Bantuan FAQ

Siapkan dokumen dengan tangkapan layar dan sorot kode yang relevan (jika perlu) untuk yang berikut:

• Informasi pada aplikasi ujung depan seperti objek atau kontrol, properti objek dll.
• Informasi tentang permintaan Database (jika belum ada)
• Informasi tentang properti Database seperti Primary Key, Foreign Key dll. Dan bagaimana mereka memastikan konsistensi dan akurasi data.
• Panduan terperinci di seluruh proyek dengan menggunakan tangkapan layar dari semua jenis layar yang mungkin menggunakan ujung depan dan ujung belakang setelah menjalankannya dengan data sampel, tanpa pengulangan jenis data atau layar yang serupa, dalam urutan logis.

• Masukkan data yang tidak valid dan tunjukkan yang tidak mungkin dilakukan karena Anda telah melakukan validasi data di ujung depan dan belakang.
  /* This step is not applicable if you have not used any object for getting direct input from the user like Text Field as it is obvious that you cannot get invalid data through indirect input. */

• Tunjukkan bahwa tidak ada kesalahan dalam program atau inkonsistensi dalam data jika ada kegagalan tiba-tiba di server atau sistem klien dengan menjelaskan kode yang relevan.

• Setelah memberikan data sampel melalui ujung depan, Anda dapat menyertakan kueri sampel di ujung belakang untuk pengambilan data langsung dari server dan juga menyertakan kueri sampel DML yang dapat membantu menyiapkan statistik vital data Anda.

Anda harus memeriksa ini sendiri sebelum mendokumentasikannya sehingga jika klien Anda meminta demo dengan data sampel, Anda dapat menunjukkan bagaimana proyek itu benar-benar bekerja. Juga, pastikan bahwa kode ujung depan Anda memiliki baris komentar yang sesuai.

• Terakhir, akhiri dengan statistik seperti jumlah total baris kode, jumlah hari yang dihabiskan untuk proyek, total berapa kali Anda telah memeriksa proyek, daftar semua aplikasi yang digunakan dan informasi teknis dan non-teknis lainnya.

  
  Dokumentasi Non-Teknis:

• Perincian perizinan proyek, jika berlaku.
• Aspek komersial proyek, jika ada.

Berhati-hatilah

Dokumentasi potensial yang dapat Anda berikan kepada klien hampir tidak ada habisnya. Waktu tambahan yang diperlukan untuk menghasilkan dokumentasi yang belum Anda miliki tidak dibayar.

Mengapa klien menginginkan dokumentasi ini (melebihi dan di atas kode sumber)? Apa yang akan dilakukan dengannya? Untuk siapa ini?

Jawaban atas pertanyaan-pertanyaan ini akan membantu mempersempit ruang lingkup apa yang harus disampaikan.

Sangat penting bagi Anda dan klien untuk menyetujui secara tepat dokumentasi apa yang harus disampaikan, dan apakah upaya tambahan apa pun akan diberikan kompensasi.

Jangan main tebak tebakan. Sebagian besar dokumentasi teknis tidak akan berguna bagi klien tipikal (non-teknis).

Saya mungkin akan memecah ini menjadi beberapa kategori dokumen:

Panduan:

• Panduan instalasi, cara mengaturnya di server.
• Panduan administrator, untuk cara mengkonfigurasi dan menjalankan aplikasi untuk kinerja optimal. Keamanan juga akan menjadi sesuatu yang perlu dibahas di sini supaya diketahui apa kata sandi yang dimiliki dan digunakan aplikasi ini untuk dijalankan.

Dukung:

• Jika ada masalah, prosedur apa yang akan Anda sarankan? Apakah Anda memberikan dukungan untuk jangka waktu tertentu? Saya mungkin masih memberikan satu atau dua panduan di area ini supaya orang lain tahu beberapa hal yang lebih mudah untuk dicoba seperti memulai kembali layanan atau me-reboot server.

Poin integrasi:

• Apakah ada poin integrasi pihak ke-3 untuk aplikasi ini yang membuatnya bergantung pada vendor lain selain kode Anda?