Saya adalah pencipta proyek open source yang berkembang. Saat ini, saya menjadi frustrasi ketika mencoba mencari cara terbaik untuk mengelola dokumentasi. Berikut adalah opsi yang saya pertimbangkan:
- Situs web HTML
- A Github Wiki
- File Penurunan Harga Diinangi Di Github
- Menempatkan Semua Dokumen di Github README.md
Dokumentasi sudah ditulis dalam Markdown, saya tidak tahu bagaimana saya ingin membuatnya tersedia. Saya benar-benar tertarik pada Git karena saya bisa membuat cabang dan memberi tag pada dokumentasi seperti halnya saya bisa membuat cabang dan memberi tag pada sumbernya.
Saya bisa menggunakan perpustakaan Markdown untuk menerjemahkan Markdown ke HTML dan menampilkannya di situs web gaya. Saya perlu mengunggah perubahan ke situs web kapan pun ada perubahan, dan akan sulit untuk mengelola semua "tag" dokumentasi yang berbeda.
Github Wikis (sejauh yang saya tahu) tidak berubah sesuai dengan cabang Anda. Jadi, saya hanya bisa memiliki versi "master" dari dokumentasi dalam bentuk Github Wiki pada waktu tertentu.
Menempatkan semuanya dalam README Github agak rapi. Saya mendapatkan percabangan dan penandaan, tetapi sedikit melelahkan untuk digunakan dan tidak cocok untuk navigasi yang mudah.
Apakah saya melewatkan beberapa solusi hebat? Opsi apa lagi yang saya miliki?
sumber
Jawaban:
Satu hal yang akan saya katakan adalah dokumentasi HARUS berada di file kode sumber (menggunakan markup apa pun yang Anda inginkan) dan kemudian dokumen dihasilkan secara otomatis dari ini.
Setidaknya di situs Anda, Anda dapat membuat unduhan yang diformat dari dokumen sebagai bagian dari paket sumber sehingga pengguna tidak memerlukan alat dokumen khusus
Kemungkinan orang lain memperbaiki / menambahkan fungsi dan kemudian mengedit / menambahkan sedikit dokumentasi markup yang berbatasan langsung dalam file yang sama mungkin rendah. TAPI peluang mereka menemukan file yang sama sekali berbeda dalam repositori dokumen berbeda untuk melakukan hal yang sama sedikit kurang dari nol.
Anda selalu dapat memiliki tutorial.h yang berisi blok teks besar jika Anda mau - tetapi perlakukan sebagai bagian dari sumbernya
sumber
Jika proyek Anda adalah pustaka, tidak ada yang mengalahkan dokumentasi gaya javadoc untuk mendokumentasikan sintaksis API dari komentar dalam kode itu sendiri.
Adapun dokumentasi tentang tutorial, contoh penggunaan, dll. Saya sangat merekomendasikan menggunakan format wiki. Proyek lain yang saya lihat memiliki halaman terpisah untuk cabang yang berbeda. Ketika Anda memulai cabang baru, Anda cukup menyalin hal-hal yang belum berubah ke halaman baru dan memperbarui dari sana.
Alasan saya merekomendasikan wiki adalah anekdotal, tetapi dari pengalaman pribadi. Saya telah menyumbang pembaruan dokumentasi untuk proyek sumber terbuka pada beberapa kesempatan, tetapi mereka semua menggunakan wiki. Jika saya mencoba untuk mencari tahu sesuatu dan dokumentasinya menyesatkan atau tidak membantu, setelah saya mengetahuinya saya akan memperbarui wiki saat saya di dokumen dan itu segar di pikiran saya. Jika bukan karena rasa memberi kembali, paling tidak karena saya tahu saya mungkin perlu mencarinya sendiri dalam satu atau dua tahun.
Jika tidak ada wiki, penghalang untuk masuk terlalu tinggi untuk mengganggu, antara mencari tahu bagaimana dokumentasi dihasilkan, di mana itu disimpan, mendapatkan yang terbaru dari kontrol sumber, bagaimana membuat pengeditan, membuat pengeditan yang sebenarnya, dan menavigasi milis untuk mendapatkan tambalan diterima.
Jika Anda ingin kontrol ketat atas dokumentasi Anda, tentu saja gunakan apa pun yang paling nyaman bagi Anda, karena Anda akan menjadi satu-satunya yang memperbaruinya. Jika Anda ingin mendorong partisipasi masyarakat, gunakan wiki.
sumber
File Penurunan harga Host dengan sumbernya bekerja dengan sangat baik.
Alat dokumen berbasis RST , misalnya, dapat membuat HTML atau LaTex (dan PDF) dari satu set dokumen.
Ini - pada dasarnya - menggabungkan opsi 1 Anda dan opsi 3.
sumber
Jika Anda tidak keberatan mengonversi dokumen dari Markdown ke reStructuredText, pertimbangkan Sphinx . Semudah penurunan harga, tapi jauh lebih kuat.
sumber