Saya bertugas memimpin upaya dokumentasi untuk produk perangkat lunak yang ada, yang sepenuhnya tidak berdokumen, - sumber daya apa yang ada untuk membantu saya?

Saya seorang pengembang perangkat lunak di sebuah perusahaan teknologi. Saya telah ditugaskan memimpin upaya dokumentasi untuk produk yang saya kerjakan. Tujuannya adalah untuk menghasilkan dokumentasi internal untuk pengembang, dan proyek mengalir ke sisi bisnis, di mana mencakup dokumentasi persyaratan.

Proyek ini menantang. Secara khusus, saya berurusan dengan produk yang: - telah ada sejak lama, setidaknya 6 tahun. - tidak memiliki bentuk dokumentasi selain beberapa potongan kecil, usang di sana-sini. - Memiliki komentar dalam kode, tetapi mereka teknis dan tidak menyampaikan perilaku over-arching (bahkan di sisi teknis). - sebagai konsekuensi dari memiliki sedikit atau tidak ada dokumentasi, seringkali tidak perlu rumit di bawah selimut

Selain itu, kami belum diberi banyak waktu untuk mengerjakan proyek ini.

Saya tidak memiliki dokumentasi formal atau latar belakang penulisan, pelatihan, atau pengalaman. Saya telah menunjukkan beberapa kemampuan dalam menulis / komunikasi di sekitar kantor, yang mungkin mengapa saya ditugaskan untuk proyek ini.

Silakan bagikan saran atau rekomendasi Anda untuk sumber daya untuk membantu saya mempersiapkan dan menangani proyek ini. Saya mencari referensi ke buku / situs web / forum / apa pun, untuk membantu saya menemukan desain rencana dengan tonggak, belajar tentang praktik terbaik, delegasi tugas, templat, buy-in, dll.

Saya berharap secara khusus untuk penargetan sumber daya atau memberikan perhatian khusus untuk memperkenalkan dokumentasi yang baik untuk proyek yang ada, tidak berdokumen ,.

Saya biasanya menggunakan wiki dan hanya mengirim spam di sana saat saya melalui proses penemuan. Wiki karena Anda mendapatkan pencarian dan riwayat serta fungsi pengeditan tim. Alat yang tepat kurang penting daripada memiliki pencarian yang berfungsi dan membuat semua orang menggunakannya. Harapkan itu akan menjadi sangat kasar pada awalnya, tetapi dorong orang untuk membuat catatan kasar saat mereka pergi karena hanya itu yang akan Anda dapatkan pada awalnya.

Beberapa hal yang sangat membantu:

• punya editor. Anda, mungkin, pada awalnya, tetapi jika Anda memiliki anggaran menjadikannya bagian dari pekerjaan seseorang. Pilih seseorang yang ahli dalam bahasa daripada ahli teknis. Sunting untuk kejelasan daripada kesempurnaan - Anda ingin mendorong orang untuk menulis entri yang bagus tetapi Anda harus membimbing mereka terlebih dahulu.
• menggunakan diagram, tetapi mandat bahwa alat yang relevan digunakan, gambar dihasilkan dan file sumber dilampirkan ke halaman. Dengan begitu orang dapat mengedit gambar Anda menggunakan alat yang tepat alih-alih MS-Paint. Beberapa hal menyedot lebih dari diagram yang benar-benar bagus dibangun di Visio yang Anda tidak memiliki dokumen sumber lagi, hanya PNG yang diekstraksi darinya.
• Dorong pengaturan ulang dan pengeditan. Meskipun awalnya tidak bagus, Anda perlu orang untuk mengumpulkan informasi dan memperbaiki kesalahan. Bimbing orang untuk melakukan ini dengan baik.
• bawa ini di pertemuan tim mingguan Anda. Raih daftar hasil edit terbaru sebelum Anda masuk dan pujilah orang-orang yang telah menambahkan sesuatu yang bermanfaat, lalu tanyakan mengapa mereka yang belum, belum.

Saya sudah mulai dengan gambar mesin virtual MediaWiki di masa lalu karena sangat cepat dan mudah untuk memulai, jadi orang-orang mengatakan "terlalu sulit" tidak mendapatkan traksi awal.

Jika bahasa / lingkungan Anda mendukungnya menggunakan alat tipe JavaDoc / NDoc untuk mengekstraksi komentar saat Anda menambahkannya adalah pendekatan tingkat rendah yang baik. Tapi itu kurang berguna daripada dokumentasi tingkat tinggi, dan meskipun alat semacam dukungan menambahkan hal-hal tingkat tinggi, membuatnya dari tidak menggunakan hanya alat-alat itu tidak perlu melelahkan.

Jika Anda mendokumentasikan kode itu sendiri, dan tidak melakukan dokumentasi pengguna akhir, Doxygen adalah alat yang hebat jika bahasa pengembangan Anda didukung. Anda menjalankannya di atas kode Anda, dan itu membuat situs web yang mencantumkan semua fungsi, kelas, dll. Kemudian Anda dapat menambahkan komentar kode yang diformat khusus untuk hal-hal kelompok dan menambahkan lebih detail. Ini adalah cara yang bagus untuk mendokumentasikan basis kode secara bertahap.

Berkenaan dengan mendokumentasikan kode itu sendiri, jika Doxygen tidak sesuai dengan kebutuhan Anda, ada banyak alat alternatif yang tersedia. Wikipedia memiliki daftar hampir 50 alat semacam itu dan menyertakan perincian fungsi dan dukungan bahasa mereka.

Penafian: Saya dikaitkan dengan salah satu alat, Imagix 4D .

Ini hanya beberapa ide yang mungkin berguna pada tingkat tertentu:

Pernahkah Anda berpikir tentang bagaimana bentuk dokumentasi ini pada akhirnya: Akan menjadi dokumen Word, DVD, situs dengan serangkaian halaman yang meruntuhkan aplikasi, alat blogging yang hanya mengoceh detail aplikasi saat seseorang menyelam melalui itu, menggunakan beberapa sistem manajemen dokumen off-the-shelf seperti Share Point, atau yang lain? Mendapatkan Hasil akan menjadi contoh dari sebuah buku on-line yang merupakan serangkaian halaman misalnya.

Apa jenis kontrol versi dan proses pengeditan yang Anda ingin ambil dari dokumentasi ini adalah masalah lain yang mungkin perlu dipertimbangkan sebelum Anda terlalu jauh dalam hal ini. Bagaimana Anda ingin menangani pembaruan dan perubahan.

Umpan balik kemungkinan menjadi dimensi lain yang menarik tentang ini karena apa pun yang Anda buat mungkin akan ada lebih dari beberapa kritik dan seberapa baik perubahan itu diprioritaskan dan dicekik adalah pertanyaan lain yang akan saya pertimbangkan sebelum mengeluarkan versi pertama.

Semoga berhasil!

Membangun Dokumentasi, seperti membangun semua jenis perangkat lunak lain, adalah proses yang pada dasarnya rumit.

Itu sebabnya pengembang perangkat lunak menemukan metode Agile.

Dokumentasi hanyalah perangkat lunak tanpa kompiler. Metode yang sama untuk proyek perangkat lunak berlaku untuk proyek dokumentasi. Alasannya persis sama.

Ketika Anda menulis perangkat lunak, Anda mulai dengan kasus penggunaan (atau cerita pengguna). Dokumentasi tidak berbeda.

Anda memprioritaskan kasing penggunaan dengan perkiraan anggaran.

Anda memiliki sprint.

Anda memiliki rilis.

Anda melakukan jaminan kualitas - pengujian - ulasan - koreksi dan pelepasan kembali.

Ini persis seperti membangun software.

Siapa penggunamu? Masalah apa yang mereka miliki? Bagaimana dokumen akan menyelesaikan masalah mereka? Memprioritaskan. Sprint. Akhirnya, Anda akan merilis.