Mendokumentasikan bahasa pemrograman: Referensi Manual

Kami sedang melihat pembenahan dokumentasi di seluruh lini produk kami. Bagian dari itu termasuk manual referensi untuk bahasa pemrograman yang digunakan sebagai bagian dari sistem.

Saat menulis manual referensi untuk bahasa pemrograman, apa cara terbaik untuk menyusunnya agar dapat digunakan secara maksimal bagi yang baru menggunakan bahasa tersebut?

Apa aspek utama untuk setiap kata kunci yang didokumentasikan?

• Sintaksis
• Deskripsi
• Argumen - jika ada
• Nilai pengembalian - jika berlaku
• Contoh penggunaan?
• Adakah yang lain yang saya lewatkan?

Haruskah konsep (seperti strategi penguncian, detail terkait kinerja) juga didokumentasikan dalam manual referensi ini, atau apakah itu dokumen yang terpisah?

_{Ini untuk konsumsi eksternal. Kami sudah memiliki set dokumen lengkap (lihat: http://www.rocketsoftware.com/u2/resources/technical-resources ). Mengerjakan apa yang harus kita lakukan berbeda - saya sudah punya ide, tetapi seperti biasa, saya berusaha untuk tidak hanya mengandalkan pendapat saya.}

_{Pemirsa: Pengembang teknis menggunakan basis data & alat kami untuk menghasilkan perangkat lunak di banyak industri.}

Atur dokumentasi sesuai dengan kebutuhan audiens target.

Dalam kasus Anda, audiens utama tampaknya adalah pengembang perangkat lunak. Bagian yang perlu dipertimbangkan di sini adalah untuk mengatasi "sub-audiens" yang berbeda dari yang ini:

1. Halo Dunia.
   Mereka yang ingin cepat merasakannya, hanya membangun dan menjalankan aplikasi sampel untuk melihat tampilannya.
   Pikirkan audiens seperti yang ditangani oleh MySQL "aturan 15 menit" :
   

   _{... seorang pengguna untuk dapat menjalankan MySQL dan berjalan 15 menit setelah dia selesai mengunduhnya.}

2. Fundamental.
   Untuk orang-orang yang mau dengan cepat mempelajari hal-hal yang diperlukan untuk mulai memproduksi perangkat lunak yang berfungsi
3. Topik lanjutan.
   Untuk pengembang yang sudah akrab dan berlatih dengan fundamental, tertarik untuk mengetahui apa yang ada di luar sana. Topik arus utama yang belum tercakup dalam Fundamentals .
4. Panduan Gaya / Praktek yang Disarankan.
   Saran dan bimbingan subyektif untuk mereka yang tertarik dengan cara Anda merekomendasikan untuk melakukan sesuatu.
   _{Pertanyaannya tidak menunjukkan apakah ini dapat memiliki audiens yang besar dalam kasus Anda, jadi opsi yang perlu dipertimbangkan adalah memasukkannya sebagai bagian / lampiran dari topik Tingkat Lanjut atau bahkan menjatuhkannya sepenuhnya.}
5. Keanehan.
   Topik tidak jelas, di luar arus utama, yang mungkin menarik bagi sebagian kecil audiens Anda. Misalnya, jika Anda memiliki legacy line, atau hal-hal seperti peningkatan / migrasi / interoperabilitas dengan legacy - taruh di sini. Jika ada beberapa efek samping untuk beberapa fungsi di lingkungan "eksotis" tertentu, itu berlaku di bagian ini.

^{Bagaimana jika sesuatu dalam manual ini dipertanyakan / ambigu? Bagaimana jika ternyata penjelasan menyeluruh tentang konsep tertentu akan membuat manual itu terlalu sulit untuk dibaca? Bagaimana jika ternyata versi manual tertentu memiliki kesalahan?}

Dua hal yang perlu dipertimbangkan untuk pengelola adalah:

1. Spesifikasi teknis / formal.
   Setiap kali ada topik yang dipertanyakan / ambigu / sulit dijelaskan dalam manual, pembaca dapat dirujuk ke paragraf tertentu dalam spesifikasi untuk pernyataan "resmi" yang ketat dan jelas. Deskripsi sintaks bahasa yang ketat dan lengkap (dan kemungkinan besar membosankan) akan lebih baik masuk ke sana.
   Pertimbangan terpenting untuk Spesifikasi adalah keakuratan dan kelengkapan teknis, meskipun hal ini harus mengorbankan keterbacaan.
2. Suplemen online.
   Hanya cadangan beberapa URL dan letakkan di awal setiap dokumen yang Anda rilis, sehingga orang-orang bertanya-tanya apa yang baru saja mereka baca bisa pergi ke sana (alih-alih mengganggu pengelola manual) dan menemukan kesalahannya dijelaskan.

   _{Errata> Fundamentals> Release 2.2> Typo di halaman 28, kalimat kedua dimulai dengan keberuntungan , bacalah kunci .}

Misalnya, pengelola manual tampaknya tertarik pada deskripsi lengkap dan akurat tentang konkurensi dan mengunci spesifikasi formal - letakkan di sana. Pembaca topik Fundamental atau Lanjutan mungkin tertarik dalam ikhtisar / pengantar / panduan diekstraksi dari spesifikasi dan disesuaikan dengan kebutuhan mereka dll.

_{Mungkin bermanfaat untuk mengatur studi perbandingan dokumentasi referensi yang disediakan untuk bahasa lain seperti bahasa Anda. Tujuan penelitian ini untuk meningkatkan pengalaman yang diperoleh oleh mereka yang melakukannya sebelumnya dan belajar bagaimana menghindari kesalahan yang mereka buat.}

_{Yang terakhir tetapi tidak kalah pentingnya, pertimbangkan untuk mengatur pengembangan dokumentasi dengan cara yang mirip dengan pengembangan perangkat lunak. Maksud saya hal-hal seperti kontrol versi, rilis reguler, pelacakan masalah, jaminan kualitas dll. Anda mungkin ingin membuat beberapa kompromi meskipun jika ternyata penulis teknis Anda tidak begitu nyaman dengan hal-hal seperti itu. Kami tidak ingin mendapatkan konten jelek "sebagai imbalan" untuk proses pengembangan yang sempurna, bukan?}

Hal pertama yang perlu Anda lakukan adalah mengevaluasi audiens. Apakah audiens Anda adalah peretas kernel Linux atau mereka perancang perangkat keras yang menggunakan alat perangkat lunak untuk melakukan pekerjaan tetapi tidak tertarik dengan perangkat lunak itu sendiri dan tidak memiliki latar belakang CS. Insinyur listrik mungkin tidak sepenuhnya jelas tentang perbedaan antara argumen const dan non-const, pointer ke objek versus referensi, dll. Jika primitif Anda memiliki nama yang berlebihan, maka Anda sebaiknya menjelaskan konsep itu pada tingkat yang sesuai untuk audiens Anda, yang mungkin tidak ada artinya jika mereka adalah programmer C ++.

Hal kedua yang perlu Anda evaluasi adalah granularitas primitif bahasa. Semakin halus rinciannya, semakin Anda perlu memberikan contoh penggunaan yang sesuai dengan spesifikasi sintaksis masing-masing primitif. Yaitu, jika Anda memiliki primitif tingkat rendah yang instantiate beberapa konteks, dan Anda perlu beroperasi dengan tiga primitif tingkat rendah lainnya sebelum Anda dapat melakukan sesuatu yang berguna, maka Anda lebih baik memiliki contoh lengkap dari beberapa fungsi yang berguna dekat- oleh dalam manual. Lihat dokumentasi openssl online untuk contoh tandingan dari dokumentasi yang hampir tidak dapat digunakan.

Pastikan untuk memasukkan penjelasan tentang efek samping dari fungsi Anda.

Dalam hal apa pun, jika Anda tidak ingin pemrogram pelanggan Anda mengutuk Anda setiap malam sebelum tidur, sertakan banyak kode contoh yang diuji yang melakukan beberapa primitif fungsional tingkat tinggi. Pastikan bahwa contoh tidak hanya potongan kode, tetapi lengkap dan dapat dikompilasi atau dapat dijalankan di luar kotak.

Secara tradisional, penulis teknologi telah membedakan antara manual referensi dan panduan pengguna . Manual referensi biasanya mencakup spesifikasi sintaksis, definisi fungsi atau primitif yang dapat dimengerti, diskusi tentang gotcha, kinerja dan efek samping, dan contoh penggunaan singkat. Panduan pengguna mencakup contoh penggunaan yang lebih luas dan diskusi tentang masalah teknik yang lebih luas. Kernigan dan Ritchie "Bahasa Pemrograman C" adalah contoh yang sangat baik untuk konvensi ini, tetapi pendekatan ini hanya berfungsi ketika bahasa yang Anda dokumentasikan relatif sederhana.

Penulis adalah manajer Divisi Layanan Rekayasa di pusat pengembangan Ready Systems Inc antara 1987 dan 1991 dengan tanggung jawab untuk mengelola tim yang terdiri dari lima penulis teknologi.