Panduan untuk menulis dokumentasi perisian pertama anda

Sebagai pemaju, kebanggaan dan kegembiraan anda adalah kod anda. Ia boleh dibaca, ia memenuhi prinsip kering, ia mencerminkan amalan terbaik, dan produk akhir adalah alat yang hebat yang menyelesaikan beberapa jenis masalah untuk pengguna sasarannya. Walau bagaimanapun, tidak kira berapa banyak kerja yang telah anda masukkan ke dalam kod anda, jika perisian anda tidak mempunyai dokumentasi, atau anda menulis dokumentasi sebagai peringatan dan memperlakukannya dengan sedikit kepentingan, kemungkinan pengguna akan mendapati sedikit kegembiraan dalam bekerja dengannya, dan Akhirnya memilih produk yang lebih mesra pengguna.

Dalam artikel ini, anda akan dapati beberapa prinsip panduan praktikal untuk mendapatkan anda dan berjalan dengan menulis dokumentasi perisian pertama anda.

Takeaways Key

Dokumentasi perisian yang baik adalah penting untuk penggunaan dan pemahaman pengguna, berfungsi sebagai alat komunikasi antara pemaju dan pengguna. Ia harus termasuk tutorial, panduan cara, panduan rujukan, dan penjelasan, memberikan panduan yang komprehensif untuk keupayaan perisian.
Penonton sasaran untuk dokumentasi harus dikenal pasti dengan jelas, kerana ini akan membentuk kandungan dan bahasa yang digunakan. Dalam konteks panduan ini, tumpuannya adalah pada dokumentasi untuk pemaju yang berbeza -beza kebiasaan dengan perisian, bukannya manual pengguna atau dokumentasi projek.
Dokumentasi harus mudah ditemui, berstruktur dengan baik, dan kerap dikemas kini. Adalah disyorkan untuk memastikan dokumentasi dekat dengan kod, dalam kawalan sumber, untuk memastikan ia tetap relevan dan tepat apabila kemas kini kod berlaku. Termasuk halaman Soalan Lazim juga boleh membantu menangani pertanyaan pengguna biasa.
Di luar dokumentasi tradisional, jawatan blog boleh berfungsi sebagai alat yang berguna untuk menjelaskan ciri -ciri perisian, menyediakan tutorial, dan berkongsi kemas kini. Ini dapat memupuk komuniti di sekitar perisian, menyumbang kepada pertumbuhan dan kejayaannya. Contoh amalan dokumentasi yang baik boleh didapati di platform seperti Greensock, React, dan Vue.js.

mengapa dokumentasi penting

Merujuk kepada perisian anda, Mike Pope mempunyai kata yang sesuai seperti ini:

Jika tidak didokumenkan, ia tidak wujud .

Kenapa itu? Nah, hanya untuk mengambil pengalaman peribadi saya sebagai contoh, saya melayari web mencari perpustakaan animasi JavaScript baru untuk mencuba dan saya jumpa satu dengan penerangan ciri -cirinya yang saya suka. Walau bagaimanapun, tidak ada dokumentasi, bahkan seksyen yang bermula, tetapi hanya halaman API yang terdedah dengan hampir tidak ada penjelasan atau contoh. Adakah anda fikir saya akhirnya menggunakan perpustakaan itu? Sudah tentu, saya tidak. Saya sangat kecewa dengannya sehingga saya berpindah ke sesuatu yang lebih masuk akal kepada saya.

kepada persoalan

mengapa perpustakaan JavaScript yang baik gagal , Nicholos Zakas memberikan jawapan berikut:

Kekurangan dokumentasi . Tidak kira betapa indahnya perpustakaan anda dan betapa bijaknya reka bentuknya, jika anda satu -satunya yang memahaminya, ia tidak melakukan apa -apa yang baik. Dokumentasi bermakna bukan hanya rujukan API autogenerasi, tetapi juga contoh yang dijelaskan dan tutorial mendalam. Anda memerlukan ketiga -tiga untuk memastikan perpustakaan anda dapat diterima dengan mudah. ​​

Satu lagi sebab penting mengapa dokumen perisian anda sangat penting ialah mereka berfungsi sebagai alat komunikasi antara diri anda sekarang dan masa depan anda, dan juga antara diri anda sekarang dan pemaju lain yang akhirnya mungkin mendapati diri mereka bekerja pada perisian anda. Walaupun anda menulis kod yang boleh dibaca dan dikomentari, ini tidak semestinya bermakna ia masih akan jelas kepada anda dalam masa enam bulan mengapa anda menulis fungsi, atau mana -mana sekeping kod anda untuk perkara itu, cara yang anda lakukan.

Dokumentasi membolehkan anda memindahkan mengapa di belakang kod. Banyak cara yang sama dengan komen kod menerangkan mengapa , dan bukan bagaimana , dokumentasi berfungsi dengan tujuan yang sama. - Panduan Pemula untuk Menulis Dokumentasi

Sudah tentu, anda mahu orang menggunakan kod anda dan juga akhirnya dapat mengemas kini dan memperbaikinya. Ini semua adalah faktor yang menyumbang kepada pertumbuhan komuniti sokongan di belakang produk anda, yang penting untuk mendapatkan keteguhan, kematangan, dan kejayaan.

ia akan menjadi sukar untuk mencapai semua ini jika perisian anda tidak mempunyai dokumen hebat untuk pergi dengannya.

dokumentasi perisian siapa untuk

Apabila menulis apa -apa, pastikan ia jelas dalam fikiran anda siapa penonton anda. Dokumen tidak terkecuali untuk peraturan ini. Melakukannya menjelaskan di kepala anda masalah penonton yang mungkin dihadapi, kebiasaan yang mungkin ada dengan produk anda atau prasyarat untuk menggunakan produk anda. Maklumat ini sangat penting dengan cara anda membuat kandungan dan bahasa yang anda gunakan.

Terdapat dua jenis dokumentasi Artikel ini tidak peduli dengan:

1. Manual Pengguna. Sebagai contoh, kakak saya mungkin memutuskan untuk menggunakan WordPress untuk menerbitkan blognya sendiri. Dia bukan pemaju, tetapi dia mendengar bahawa bukan Upur boleh mendapatkan blog mereka dan berjalan dalam masa yang singkat dengan WordPress. Sekarang dia akan memerlukan arahan mengenai cara memuat turun dan mengkonfigurasi perisian di pelayannya, cara menulis, menerbitkan, dan mengemas kini catatannya, cara menambah imej ke jawatan, dan lain -lain. Dengan kata lain, dia memerlukan pengguna manual.
2. Dokumentasi Projek. Dokumentasi semacam ini lebih berkaitan dengan projek ini daripada dengan perisian itu sendiri, walaupun beberapa kandungannya boleh masuk dalam fail ReadMe projek. Untuk meneruskan dengan contoh WordPress, selepas mendapat banyak amalan dengan WordPress, saya mungkin memutuskan saya ingin menambah ciri kepada perisian atau menetapkan bug atau dua. Dalam kes ini, saya perlu mengetahui perkara seperti changelog, konvensyen dan amalan terbaik, dasar sumbangan, bagaimana untuk mengambil bahagian dalam perbincangan pasukan yang berkaitan dengan tugas di tangan, dan lain -lain

Jenis dokumentasi yang saya fikirkan di sini terutama ditujukan kepada pemaju yang mempunyai tahap kebiasaan yang berbeza dengan perisian anda dan perlu menggunakannya dalam projek mereka. Sebagai contoh, jika saya membuat tema WordPress, maka saya perlu tahu bagaimana untuk memulakan, bagaimana untuk memasukkan helaian gaya dan dokumen JavaScript, bagaimana untuk berkomunikasi dengan pangkalan data untuk memaparkan jawatan, dan lain -lain

apa yang perlu disertakan dalam dokumentasi anda

Pendekatan yang popular adalah pembangunan yang didorong oleh ReadMe, yang diperjuangkan oleh Tom Preston-Werner. Ia terdiri daripada menulis dokumen ReadMe sebelum anda mula menulis sebarang kod. Dokumen ini adalah pengenalan kepada perisian anda dan biasanya termasuk:

• penjelasan mengenai perisian anda dan masalahnya menyelesaikan
• Contoh yang menggambarkan keadaan di mana kod anda biasanya digunakan
• pautan ke kod dan pelacak pepijat
• Soalan Lazim dan Cara Meminta Sokongan
• arahan bagaimana memasang perisian anda
• Maklumat Lesen

Walau bagaimanapun, pada pandangan saya, mempunyai dokumentasi yang kukuh yang benar -benar dapat membantu pemaju yang menggunakan perisian/perpustakaan anda harus jauh melebihi fail ReadMe klasik. Berikutan Daniele Procida, saya cadangkan anda memasukkan item berikut dalam bahan dokumentasi anda untuk pengalaman pengguna yang hebat.

tutorial

seorang pemula akan suka mencari tutorial dalam dokumen perisian anda. Tutorial adalah mengenai menunjukkan pengguna bagaimana melengkapkan projek menggunakan perisian anda, supaya mereka dapat dengan cepat memahami apa yang dapat mereka lakukan dengannya.

Tutorial adalah

pelajaran yang mengambil pembaca dengan tangan melalui satu siri langkah untuk menyelesaikan projek semacam. Mereka adalah apa yang diperlukan oleh projek anda untuk menunjukkan pemula bahawa mereka dapat mencapai sesuatu dengannya. - Daniele Procida

How-to Guides

How-to Guides membantu pengguna menyelesaikan tugas dunia nyata menggunakan perisian anda. Procida membandingkannya dengan resipi dalam erti kata bahawa mereka adalah arahan yang anda berikan kepada pengguna supaya mereka dapat mencapai matlamat tertentu. Tidak seperti tutorial, yang bertujuan untuk pemula yang lengkap, cara panduan bagaimana pengguna sudah mempunyai pengetahuan asas tentang ciri, alat, dan cara melakukan tugas mudah. ​​

Panduan Rujukan

Panduan rujukan adalah rujukan teknikal kod perisian anda - fungsi, API, dan lain -lain - dan menawarkan penerangan asas tentang cara menggunakan perisian. Sebagai contoh, anda akan dapati ilustrasi bagaimana untuk meneliti kelas tertentu, bagaimana untuk memanggil kaedah tertentu, dan sebagainya.

Panduan rujukan adalah

penerangan teknikal jentera dan bagaimana untuk mengendalikannya. - Daniele Procida

Ini adalah sekeping dokumentasi yang mungkin anda dapati dalam kebanyakan projek. Pemaju cenderung cukup baik untuk menulisnya kerana mereka tahu semua tentang kod mereka dan cara menggunakannya.

Penjelasan

Penjelasan adalah menyelam yang mendalam, atau perbincangan mengenai, topik tertentu yang anda fikir adalah relevan dengan pemahaman peringkat tinggi perisian anda. Mengenai penjelasan, Procida menunjukkan bahawa -

Bahagian dokumentasi ini jarang dibuat secara eksplisit, dan sebaliknya, coretan penjelasan bertaburan di antara bahagian lain. Kadang -kadang, bahagian ini wujud, tetapi mempunyai nama seperti

latar belakang atau nota lain dan tidak benar -benar melakukan keadilan terhadap fungsi.

Topik tidak ditakrifkan oleh tugas tertentu yang ingin anda capai, seperti panduan cara, atau apa yang anda mahu pengguna belajar, seperti tutorial. Ia tidak ditakrifkan oleh sekeping jentera, seperti bahan rujukan. Ia ditakrifkan oleh apa yang anda fikirkan adalah kawasan yang munasabah untuk cuba menutupi pada satu masa, jadi pembahagian topik untuk perbincangan kadang -kadang boleh menjadi sedikit sewenang -wenangnya.

perkara yang anda perlukan untuk memberi perhatian kepada

mari kita melalui beberapa petunjuk berguna untuk menjadikan dokumen anda mesra pengguna dan relevan.

Buat dokumen anda dapat ditemui

Adalah idea yang baik untuk meletakkan beberapa kerja untuk membuat dokumentasi perisian anda mudah dicari. Anda boleh menggunakan beberapa teknik SEO bersama -sama dengan beberapa strategi pemasaran supaya sebanyak mungkin pengguna dapat memegangnya.

Juga, apa yang anda masukkan ke dalam dokumen anda harus dianjurkan ke dalam struktur yang membuat mencari maklumat khusus angin. Steve Konves mengesyorkan anda menyusun dokumen anda dalam pokok yang dikaitkan dengan tunggal: bermula dari nod akar, yang harus diletakkan di lokasi yang jelas untuk setiap pengguna yang berminat untuk ditemui, semua item lain boleh diakses dengan mudah. Fail ReadMe projek meminjamkan dirinya untuk berfungsi dengan baik sebagai nod akar yang hebat untuk seluruh pokok.

Juga, jika anda menerima permintaan bantuan dari pengguna perisian anda, anda boleh menulis jawapan dan menjadikannya tersedia dalam halaman FAQ yang mudah diakses. Melakukannya akan mengurangkan masa yang anda habiskan untuk membantu pengguna, tetapi ia juga akan memberi anda gambaran yang lebih jelas tentang jenis pengguna maklumat yang paling kerap diperlukan supaya anda dapat mendokumentasikannya terlebih dahulu dan menyimpannya di tempat yang menonjol dalam dokumen anda.

Pastikan dokumen anda terkini dan bebas daripada pepijat

dengan mudah mengakses dokumentasi perisian anda adalah hebat, tetapi jika pengguna mengetahui bahawa kandungannya sudah lapuk atau kod sampel atau arahan membawa kepada hasil kereta, ini akan mengecewakan, sekurang -kurangnya. Namun, Steve Konves mencadangkan anda menyimpan dokumen anda dekat dengan kod - misalnya, dalam kawalan sumber. Dengan cara ini, apabila pemaju mengemas kini kod itu, mereka akan melihat bahan dokumentasi, yang membuat pengemaskinian dokumen itu lebih mungkin berlaku.

Juga, untuk meminimumkan kejadian pepijat, menguji arahan dan sampel kod yang anda berikan dalam dokumen anda.

tip tambahan dan beberapa contoh popular

Jangan berhenti di dokumentasi. Catatan blog sangat bagus untuk membuat perisian anda dan ciri -cirinya diketahui oleh penonton yang berpotensi pengguna. Gunakan blog anda untuk menawarkan penjelasan mengenai apa yang dilakukan oleh produk anda, menyampaikan tutorial, petua dan helah yang mesra pengguna, berjalan kaki, terangkan kemas kini, dan lain-lain. Anda boleh memasukkan blog anda di laman web yang berdiri sendiri yang didedikasikan untuk perisian anda-mungkin dengan a Forum - di mana komuniti yang kuat dapat berkumpul dan berkembang.

Contoh hebat idea dokumentasi yang lebih luas ini dalam pandangan saya dilaksanakan oleh Greensock, platform animasi JS yang berjaya, yang saya dapati saya menggunakan banyak, tidak kurang kerana laman webnya tersedia mudah digunakan dan baik Dokumen berstruktur, forum super berguna, catatan blog, petua cepat, dan banyak lagi.

React and Vue.js juga boleh dikira sebagai contoh hebat. Sebaik sahaja anda mengakses laman web masing -masing, halaman utama memberitahu anda apa setiap perpustakaan yang baik untuk dalam slogan cepat, dan kemudian masuk ke dalam maklumat lanjut tentang mengapa perpustakaan boleh dianggap sebagai pilihan yang baik untuk projek anda. Kedua -dua laman web membuat permulaan yang kurang menakutkan menggunakan perkenalan lembut, coretan ilustrasi, pemula tugas pendek dapat dicapai menggunakan taman permainan, dan lain -lain. Setelah pengguna mendapat sedikit keyakinan dengan perisian baru, mereka dapat mencari dokumen API yang lebih teknikal dengan mudah, ditambah halaman memperincikan cara mendapatkan bantuan, memaparkan maklumat mengenai ekosistem, menawarkan bahagian berita atau blog, dan lain -lain

Untuk meninggalkan zon JS dan masuk ke dalam bidang perpustakaan UI yang popular dengan laman web yang hebat, saya tidak boleh meninggalkan bootstrap. Di laman web Bootstrap, anda akan dapati apa yang perpustakaan yang baik dan bagaimana untuk memulakan dengan cepat, serta dokumen yang komprehensif dan berstruktur dengan baik dan blog untuk memastikan pengguna dikemas kini pada apa yang baru.

Kesimpulan

Menulis dokumentasi yang baik mempunyai cabarannya, tetapi ia pastinya membayar seratus kali jika anda berfikir betapa mudahnya bagi pengguna anda untuk melaksanakan keupayaan perisian anda. Ini seterusnya menyumbang kepada populariti perisian anda, yang menjadikannya menarik dan oleh itu terbuka kepada kemungkinan menimbulkan masyarakat pemaju yang sanggup melabur masa mereka dalam mempelajari secara mendalam dan menyumbang kepada pertumbuhan, kestabilan, dan jangka panjangnya penggunaan.

Soalan Lazim (Soalan Lazim) Mengenai Dokumentasi Perisian Menulis

Apakah unsur -unsur utama yang perlu dipertimbangkan semasa menulis dokumentasi perisian? Bahasa yang digunakan harus jelas, ringkas, dan mudah difahami. Dokumen ini harus berstruktur dengan baik, dengan aliran maklumat yang logik. Ia juga penting untuk memasukkan visual seperti gambar rajah atau tangkapan skrin di mana perlu untuk membantu pemahaman. Akhir sekali, pastikan dokumen itu dikaji semula dengan teliti dan diedit untuk ketepatan dan kejelasan. dan bahasa yang jelas. Elakkan jargon dan istilah teknikal sebanyak mungkin. Jika anda mesti menggunakannya, pastikan anda memberikan definisi yang jelas. Susun kandungan anda secara logik dan gunakan tajuk dan subheadings untuk memudahkannya untuk menavigasi. Sertakan jadual kandungan dan indeks untuk dokumen yang lebih panjang. Gunakan visual seperti gambar rajah, tangkapan skrin, dan video untuk menggambarkan konsep kompleks.

Apakah jenis dokumentasi perisian yang berlainan? dan dokumentasi teknikal. Dokumentasi sistem menyediakan gambaran keseluruhan sistem perisian, termasuk seni bina dan aliran data. Dokumentasi Pengguna menyediakan arahan tentang cara menggunakan perisian dan termasuk manual pengguna dan panduan bantuan. Dokumentasi teknikal dimaksudkan untuk pemaju dan termasuk komen kod, dokumentasi API, dan panduan pembangunan. perisian. Ini mungkin disebabkan oleh ciri -ciri baru yang ditambah, ciri -ciri sedia ada yang diubah suai, atau pepijat yang ditetapkan. Ia juga merupakan idea yang baik untuk mengkaji semula dokumentasi secara berkala untuk memastikan ia masih tepat dan relevan.

Alat apa yang boleh saya gunakan untuk menulis dokumentasi perisian?

Terdapat banyak alat yang tersedia untuk menulis dokumentasi perisian, termasuk pemproses perkataan, penjana dokumentasi, dan alat dokumentasi khusus. Beberapa pilihan popular termasuk Microsoft Word, Google Docs, Doxygen, dan Sphinx. Pilihan alat bergantung pada keperluan khusus anda dan kerumitan perisian.

Bagaimana saya dapat memastikan kualiti dokumentasi perisian saya? Dan edit kerja anda dengan teliti. Pertimbangkan untuk mempunyai rakan sekerja atau editor profesional mengkaji dokumen anda. Gunakan gaya dan format yang konsisten sepanjang dokumen. Pastikan maklumat itu tepat, terkini, dan relevan. Akhir sekali, pertimbangkan untuk mendapatkan maklum balas daripada pengguna untuk mengenal pasti bidang untuk penambahbaikan.

Apakah peranan visual dalam dokumentasi perisian? Mereka boleh membantu menggambarkan konsep yang kompleks, menjadikan mereka lebih mudah difahami. Mereka juga boleh memecahkan blok besar teks, menjadikan dokumen lebih mudah dibaca. Contoh visual termasuk gambar rajah, tangkapan skrin, carta aliran, dan video. . Memecahkan blok besar teks dengan visual dan titik peluru. Gunakan contoh dan kajian kes untuk menggambarkan konsep. Sertakan elemen interaktif seperti kuiz atau latihan di mana sesuai.

Apakah kepentingan konsistensi dalam dokumentasi perisian? Ia juga memberikan dokumen rupa dan rasa profesional. Konsistensi berlaku untuk bahasa, gaya, format, dan visual.

Bagaimana saya dapat meningkatkan kemahiran saya dalam menulis dokumentasi perisian? Baca dokumentasi perisian lain untuk belajar dari mereka. Mengambil kursus atau bengkel mengenai penulisan teknikal. Dapatkan maklum balas mengenai kerja anda dan terbuka kepada kritikan. Tetap dikemas kini dengan trend terkini dan amalan terbaik dalam dokumentasi perisian.

Atas ialah kandungan terperinci Panduan untuk menulis dokumentasi perisian pertama anda. Untuk maklumat lanjut, sila ikut artikel berkaitan lain di laman web China PHP!