Ya paling pasti TETAPI:
- Pembusukan tautan akan menjadi masalah, idealnya menghasilkan tautan secara dinamis dari dokumen target yang diketahui tetapi mendapatkan awalan dari beberapa bentuk konfigurasi. Jika server berubah maka Anda dapat menjaga kode yang lebih lama valid dengan memperbarui elemen konfigurasi ini. Anda juga dapat membuat dokumen tersedia secara lokal juga hanya dengan mengubah konfigurasi awalan ini.
- Versi : Dengan semangat yang sama, jika Anda dapat menyertakan versi dalam tautan dalam beberapa kapasitas sehingga tautan selalu mengarah ke versi dokumentasi yang benar.
- Jadikan dokumen dapat diedit Sesuatu seperti situs jenis wiki untuk dokumentasi Anda di mana Anda dapat memperbaiki kesalahan secara dinamis, idealnya juga memungkinkan pengguna untuk berkomentar langsung pada halaman. ini akan membuat lebih mudah bagi pengguna Anda untuk berpartisipasi dan menemukan apa yang mereka butuhkan dan Anda akan mendapatkan informasi emas untuk menjaga dokumen Anda dalam kondisi kerja yang baik tetapi pastikan Anda memantau secara teratur dan sebagian besar dari semua berpartisipasi secara aktif sendiri.
- Templat yang dihasilkan meminta sistem build Anda membuat templat dasar untuk dokumentasi dari anotasi dalam kode secara langsung. Tetap sederhana, tetapi ini akan memastikan bahwa setiap tautan selalu mengarah ke dokumentasi yang valid. Jika Anda menggunakan wiki pastikan Anda dapat mendorong templat ini dengan mudah, dan pastikan Anda dapat mempromosikan situs dokumentasi dengan cara yang sama seperti yang Anda lakukan untuk kode Anda (memiliki situs pengembang yang berbeda dari situs prod dan mempromosikan kode ke prod akan melakukan sisipan di situs prod secara otomatis).
Jika Anda mengembangkan dengan Java atau .NET dokumen tersebut dapat dimasukkan dalam file jar atau file DLL dan dengan mengubah awalan kode Anda bisa mengambilnya secara lokal.
Jika Anda benar-benar memilih pendekatan wiki, saya sangat merekomendasikan DokuWiki untuk kesederhanaannya dan karena itu didasarkan pada file teks datar yang akan membuatnya sangat ramah untuk injeksi otomatis dari sistem build. Yang mengatakan, saya tidak cukup tahu tentang lingkungan Anda atau pelanggan untuk benar-benar tahu apakah ini akan cocok YMMV.
Beberapa alat paling sukses yang saya buat mengambil pendekatan serupa di mana pesan kesalahan ditargetkan ke pengguna aktual yang kemungkinan besar akan melakukan tugas. Itu berarti bahwa saya harus BANYAK pengecualian menangkap dan membungkus untuk memastikan kesalahan berada pada tingkat abstraksi yang sesuai. Saya juga memastikan bahwa setiap pesan kesalahan akan menyertakan sumber kesalahan yang paling mungkin dan menunjuk ke solusi potensial "Apakah Anda lupa untuk menetapkan nilai konfigurasi xxxx?", "Pastikan xxx dan yyy tidak bertentangan dengan memberi mereka nama yang berbeda" dll. Di mana XXX dan yang lainnya akan dihasilkan dari konteks di mana kesalahan terjadi.
Pendekatan ini agak sederhana tetapi juga lebih terbatas. Namun ada sisi positifnya bahwa dokumentasi akan selalu ada ketika tidak diperlukan pembusukan tautan.
Pendekatan Anda adalah evolusi selanjutnya. Jauh lebih kompleks tetapi juga memiliki potensi pengembalian yang jauh lebih besar. Meskipun akan mahal tetapi jika dilakukan dengan benar akan dengan mudah membayar sendiri.