Ada apa dengan keengganan dokumentasi di industri?


47

Tampaknya ada keengganan untuk menulis bahkan dokumentasi paling dasar. README proyek kami relatif telanjang. Bahkan tidak ada daftar dependensi yang diperbarui dalam dokumen.

Adakah sesuatu yang tidak saya sadari dalam industri yang membuat programmer tidak suka menulis dokumentasi? Saya bisa mengetik paragraf dokumen jika diperlukan, jadi mengapa orang lain begitu benci?

Lebih penting lagi, bagaimana saya meyakinkan mereka bahwa menulis dokumen akan menghemat waktu dan frustrasi kita di masa depan?


13
Karena kita tahu apa yang kita lakukan! Mengapa kita harus meluangkan waktu seharian untuk menuliskan apa yang sudah kita ketahui dan tidak akan pernah lupa!?!? Serius, saya berurusan dengan hal yang sama setiap hari bekerja pada basis kode yang memulai proses desainnya 7 tahun yang lalu dan telah diperbarui setiap hari sejak oleh tim mana saja dari 4-7 insinyur. Dokumentasi adalah sesuatu yang selalu kita perjuangkan, tetapi merupakan kejahatan yang perlu.
Ampt

61
Karena pengalaman telah membuktikan bahwa tidak ada yang membaca dokumen.
user16764

7
Dari sudut pandang bisnis, rim dokumentasi yang membebani uang perusahaan di sini dan sekarang, ketika Anda bisa bekerja pada proyek berikutnya untuk menghasilkan uang. Yang perlu selalu menghasilkan keuntungan adalah tekanan yang Anda rasakan terhadap dokumentasi waktu "buang-buang waktu". Plus, tidak ada yang pernah membaca dokumen dan malah membaca sumber karena hanya mereka yang memiliki otoritas tertinggi.
Patrick Hughes

14
Menyinkronkan dokumen dengan kode terbaru dapat menjadi "menantang", jika Anda menulis pada tingkat yang lebih tinggi daripada Javadoc atau yang setara.
Dan Pichelman

12
Itu tidak menyenangkan ...

Jawaban:


21

Saya pikir tidak ada gunanya berspekulasi tentang motivasi orang-orang yang tidak mengadopsi sesuatu yang Anda pikir merupakan praktik yang baik atau yang terus melakukan sesuatu yang Anda anggap sebagai praktik buruk. Dalam bisnis ini, orang-orang yang termasuk dalam satu atau kedua kategori tersebut akan jauh lebih banyak daripada orang-orang yang akan Anda temui, jadi berhentilah membuat diri Anda gila.

Sebaliknya, fokuslah pada masalah dan kemungkinan resolusi.

1. Tulis Dokumentasi yang Baik Sendiri

Mungkin tidak realistis untuk berharap bahwa semua orang di tim Anda akan mengarahkan upaya mereka ke hal-hal yang Anda lihat sebagai masalah. Ini terutama benar jika Anda adalah pendatang baru di tim. Saya berani menebak Anda memang demikian, karena jika Anda adalah anggota pendiri tim, sepertinya Anda sudah bisa menyelesaikan masalah ini sejak dini.

Sebagai gantinya, pertimbangkan untuk bekerja sendiri dengan tujuan menulis dokumentasi yang bagus dan membuat orang menggunakannya. Misalnya, jika seseorang di tim saya bertanya kepada saya di mana kode sumber untuk Proyek A adalah atau konfigurasi khusus apa yang dibutuhkan Proyek A, saya mengarahkan mereka ke halaman wiki Proyek A.

Jika seseorang bertanya kepada saya bagaimana menulis implementasi baru dari Pabrik F untuk mengkustomisasi sesuatu untuk Klien C, saya memberi tahu mereka itu ada di halaman 10 dari panduan pengembang.

Sebagian besar pengembang benci mengajukan pertanyaan yang dapat membuat mereka terlihat seperti mereka tidak bisa hanya "membaca kode" bahkan lebih dari mereka membenci membaca dokumentasi, jadi setelah cukup banyak balasan seperti ini, mereka akan pergi ke dokumen terlebih dahulu.

2. Buktikan Nilai Dokumentasi Anda

Pastikan Anda mengambil setiap kesempatan untuk menunjukkan di mana dokumentasi membuktikan nilainya (atau akan, jika digunakan). Cobalah untuk bersikap halus dan hindari "Sudah kubilang," tapi sangat sah untuk mengatakan hal-hal seperti

Untuk referensi di masa mendatang, halaman wiki proyek ini memiliki informasi tentang cabang kode inti yang dibuat untuk dukungan berkelanjutan dari rilis 2.1, jadi di masa depan kita dapat menghindari harus melakukan tes regresi penuh jika orang-orang yang mempertahankan versi yang dirilis memeriksa wiki sebelum memeriksa kode.

atau

Saya sangat senang saya menuliskan langkah-langkah untuk melakukan Tugas T. Saya tidak benar-benar peduli jika tidak ada orang lain yang menggunakannya - itu sudah menghemat lebih banyak waktu daripada yang saya habiskan untuk menulisnya.

3. Dapatkan Manajemen di Papan

Setelah beberapa kejadian di mana memiliki dokumentasi terbukti menghemat waktu / uang, Anda mungkin akan melihat "pencairan" yang berbeda terhadap dokumentasi. Ini adalah waktu untuk menekan titik dengan mulai memasukkan waktu dokumentasi dalam perkiraan Anda (meskipun jujur ​​saya biasanya memperbarui / membuat dokumen saat proses panjang sedang berjalan, seperti kompilasi atau check-in). Terutama jika ini adalah karyawan baru, mungkin ini tidak akan dipertanyakan, tetapi sebaliknya dipandang sebagai praktik baru yang Anda bawa dari tempat kerja sebelumnya (yang mungkin memang demikian).

Peringatan: Sebagian besar bos tidak suka membuat orang melakukan apa pun, terutama hal-hal yang tidak secara langsung terkait dengan tugas yang dapat ditagih, jadi jangan berharap dukungan ini berbentuk mandat. Alih-alih, lebih mungkin memberi Anda kebebasan relatif untuk menulis lebih banyak dokumen.

4. Dorong Dokumentasi Ketika Anda Melihatnya

Mungkin bagian dari alasan orang tidak menulis dokumen sesering yang seharusnya adalah mereka merasa tidak ada yang membacanya. Jadi, ketika Anda melihat sesuatu yang Anda sukai, pastikan untuk setidaknya menyebutkan bahwa Anda senang itu tersedia.

Jika tim Anda melakukan review kode, ini adalah waktu di mana Anda dapat memberikan satu atau dua kata yang halus untuk mendorong komentar yang baik.

Terima kasih telah mendokumentasikan solusi untuk bug B di Framework G. Saya tidak tahu tentang itu, dan saya tidak berpikir saya bisa mengerti apa yang Anda lakukan tanpa itu di sana.

Jika Anda memiliki seseorang dalam tim yang benar-benar antusias dengan dokumentasi, tidak ada salahnya menumbuhkan orang itu dengan pergi makan siang atau minum kopi dan memastikan untuk menawarkan sedikit validasi untuk mengatasi keputusasaan yang mungkin mereka dapatkan dari melihat anggota tim lainnya. tidak terlalu menghargai dokumentasi.

Lebih dari itu, itu benar-benar bukan masalah Anda kecuali Anda berada dalam posisi memimpin atau manajemen. Anda bisa menuntun kuda ke air, tetapi Anda tidak bisa membuatnya minum. Jika itu bukan kudamu, kamu mungkin tidak senang haus, tetapi yang bisa kamu lakukan hanyalah mengisi palung.


1
+1 untuk Poin # 2, langsung menjawab pertanyaan OP yang dimulai dengan "Bagaimana saya meyakinkan ...."
Ray Toal

Saya suka jawaban ini, yang lain lebih fokus pada "mengapa" daripada "bagaimana"
Rudolf Olah

@omouse - itu karena sebagian besar kasus, menulis dokumentasi tidak akan menghemat waktu dan frustrasi di masa mendatang. Mereka jarang akurat, dan orang tidak pernah membacanya bahkan ketika mereka membaca.
Telastyn

1
Prinsip-prinsip SOLID biasanya tidak menghemat waktu Anda atau menghasilkan desain yang lebih baik, karena kebanyakan orang tidak sepenuhnya memahaminya atau tidak benar-benar peduli. Dengan logika Anda, kami seharusnya tidak bercita-cita untuk menerapkannya, GRASP, atau praktik baik lainnya. Ingatkan saya mengapa Anda repot-repot berpartisipasi dalam programer lagi?
Amy Blankenship

Menurutnya sangat membantu untuk berspekulasi mengenai motivasi orang.
tymtam

55

Ada dua faktor utama dalam pengalaman saya:

Tenggat waktu

Sebagian besar perusahaan sangat didorong oleh tanggal sehingga QA, utang teknologi, dan desain aktual dipotong hanya agar manajer proyek tidak terlihat buruk atau untuk mencapai batas waktu klien yang terlalu dijanjikan. Dalam lingkungan ini di mana bahkan kualitas fungsional dipotong, maka investasi jangka panjang seperti dokumentasi memiliki sedikit peluang.

Perubahan

Praktik terbaik yang relatif baru untuk pengembang adalah untuk tidak menekankan komentar. Idenya adalah bahwa menyimpan informasi di dua tempat (kode [termasuk tes] dan komentar di sekitar kode) mengarah ke banyak overhead dalam menjaga mereka dalam sinkronisasi untuk sedikit manfaat. "Jika kode Anda sangat sulit dibaca sehingga Anda perlu komentar, bukankah waktu lebih baik dihabiskan untuk membersihkan kode?"

Saya pribadi bahkan tidak akan melihat komentar lagi. Kode tidak bisa bohong.

Dokumentasi mengikuti nada yang sama. Dengan adopsi lincah yang luas, orang-orang mengakui bahwa persyaratan berubah secara teratur. Dengan meluasnya penggunaan refactoring, organisasi kode akan bergeser secara substansial. Mengapa menghabiskan waktu mendokumentasikan semua hal yang pasti akan berubah? Kode dan tes harus melakukan pekerjaan dengan cukup baik.


11
+1 untuk "Saya pribadi bahkan tidak akan melihat komentar lagi", saya pikir ini biasa; ketika Anda tumbuh ke tingkat kenyamanan tertentu dengan kode itu sendiri, Anda dapat membacanya lebih cepat daripada komentar (dan masih lebih cepat jika komentar tidak menghalangi), dan kode itu tidak bohong
Jimmy Hoffa

40
Ini merindukan titik komentar, yang menjelaskan mengapa . Mereka tidak perlu berada di mana-mana, dan mereka tidak perlu terlalu lama, tetapi tautan yang ditempatkan dengan baik ke aturan bisnis yang menjelaskan mengapa 20 baris berikutnya dari logika yang benar-benar aneh ada dalam keadaan saat ini jauh lebih nyaman daripada mencoba bekerja keras melalui sejarah versi untuk menemukan alasan aslinya.
zzzzBov

7
@zzzzBov - tentu saja, itulah pandangan modern tentang berbagai hal. Ini telah berubah dari sudut pandang sebelumnya yang mendorong komentar yang lebih luas. Demikian juga, dokumentasi tentang apa yang dikerjakan kode telah menurun menjadi dokumentasi yang berfokus pada mengapa kode itu dijalankan (misalnya, desain dokumen).
Telastyn

8
Kode bisa berbohong. Pelanggan mungkin menginginkan sesuatu, dan diberi kode untuk melakukan sesuatu yang lain. Jadi jika semua yang Anda miliki sekarang adalah kode, benar?
thursdaysgeek

6
Kode bisa berbohong ... Saya punya metode garis 4.000 (hei, saya tidak membuatnya, saya hanya memilikinya sekarang ...) dan saya melihat koleksi yang jelas bernama "productList" jadi untuk perubahan baru saya menambahkan Produk keberatan dengan itu. Bagus. Hanya itu tidak berhasil, ternyata beberapa pengembang masa lalu "efisien" dan menggunakan kembali variabel tipe Daftar untuk menghindari mengacaukan 4.000 baris dengan terlalu banyak variabel, dan dalam lingkup itu berisi objek Pelanggan ...
Kevin Rubin

16

Ada sejumlah faktor yang berperan di sini:

  1. Kode yang ditulis dengan baik adalah dokumentasinya sendiri. Semua hal lain dianggap sama, lebih baik menulis kode yang lebih jelas yang berbicara untuk dirinya sendiri, daripada lebih banyak dokumentasi. Lakukan itu, dan Anda perlu memodifikasi lebih sedikit dokumentasi ketika Anda mengubah kode itu.

  2. Menulis dokumentasi bisa dibilang keterampilan yang berbeda dari menulis kode. Beberapa pengembang perangkat lunak lebih baik daripada yang lain. Beberapa jauh lebih baik dalam menulis kode daripada menulis dokumentasi.

  3. Dokumentasi seharusnya hanya ditulis sekali , tidak dua kali (sekali dalam kode sumber, dan sekali lagi dalam panduan programmer). Itu sebabnya kami memiliki hal-hal seperti komentar XML dan generator dokumentasi. Sayangnya, menggunakan alat-alat seperti itu bisa lebih rumit dan rumit daripada hanya menulis dokumentasi dengan tangan, itulah sebabnya Anda tidak melihat alat-alat itu banyak digunakan.

  4. Dokumentasi yang baik memakan waktu, dan sulit dilakukan dengan baik. Semua hal lain dianggap sama, mungkin ada nilai lebih untuk menulis kode baru daripada menulis dokumentasi untuk kode yang sudah ada.

  5. Ketika kode berubah, Anda juga harus mengubah dokumentasi. Semakin sedikit dokumentasi yang ada, semakin sedikit yang harus diubah.

  6. Lagipula tidak ada yang membaca dokumentasinya, jadi mengapa repot-repot?


2
kembali # 1, saya pikir itu tidak pernah terjadi, tetapi # 4 pasti benar
Rudolf Olah

3
@whatsisname: Tidak sama sekali. Tulis kode yang lebih jelas yang membutuhkan lebih sedikit dokumentasi, dan Anda perlu memodifikasi lebih sedikit dokumentasi ketika Anda mengubah kode itu.
Robert Harvey

2
@thursdaysgeek: Yang dimaksud dengan peluru itu adalah Anda tidak perlu menulis dokumentasi dua kali: sekali untuk komentar kode, dan sekali lagi untuk referensi file bantuan / programmer. Anda tentu tidak harus menulis ulang dua kali. Apakah kalian membaca hal ini?
Robert Harvey

4
# 6 ... Saya pikir ini adalah kesalahpahaman umum. Sebuah banyak orang membaca dokumentasi secara menyeluruh.
Dinamis

3
@tymek: Tanda Anda terbalik. Teman-teman, ini bukan tutorial tentang cara membuat dokumentasi; itu adalah perhitungan mengapa pengembang memiliki sikap negatif terhadapnya.
Robert Harvey

11

Gajah di dalam ruangan: Programer bukan (harus) penulis. Mereka juga tidak selalu setuju untuk menyempurnakan implementasi mereka untuk penulis teknis. Gajah kedua di dalam ruangan: Penulis teknis umumnya tidak dapat menyempurnakan rincian yang berguna untuk pengembang masa depan (bahkan jika pengembang akan berkenan menjelaskannya kepada mereka).

Suatu sistem yang kompleks dapat menjadi hampir tidak dapat dipahami dari waktu ke waktu tanpa dokumentasi yang tepat. Kode menjadi kurang bernilai secara proporsional berbanding terbalik dengan pengawasannya. Diselesaikan, manajemen mempekerjakan Insinyur Perangkat Lunak yang dapat membaca kode dan membujuk detail dari pengembang, membayarnya dengan tarif pengembang dan mengamanatkannya untuk mendokumentasikan dan memelihara dokumentasi. Penulis ini dapat membaca kode dan akan tahu pertanyaan apa yang harus ditanyakan dan akan mengisi rincian yang diperlukan. Sama seperti Anda memiliki departemen QA, Anda memiliki departemen dokumentasi internal.

Kode akan menjadi lebih berharga, karena Anda dapat melisensikannya kepada pihak ke-3 (karena ia dapat memahaminya), kode tersebut dapat lebih mudah diaudit dan ditingkatkan / difaktorkan ulang, Anda akan memiliki kode yang lebih baik digunakan kembali bahkan di mana Anda dapat dengan mudah faktor keluar versi yang lebih ringan dari perangkat lunak Anda, dan Anda akan dapat memperkenalkan pengembang baru lebih mudah ke dalam proyek, insinyur pendukung Anda akan senang bekerja untuk Anda.

Ini tidak akan pernah terjadi.


1
Belum lagi ketika mencoba menjelaskan ke kode yang ada, menjadi lebih sulit untuk memberikan deskripsi yang baik ketika kode dan fungsionalitasnya sangat kompleks sehingga tidak ada yang tahu apa yang sudah dilakukan, sehingga setiap perubahan baru memiliki dampak yang tidak dimiliki pengembang baru. tahu tentang ...
Kevin Rubin

1
Saya menyarankan bahwa "kemampuan dasar untuk mengkomunikasikan niatnya dengan (terbatas) dokumentasi" adalah keterampilan programmer yang diperlukan. Seorang programmer tidak harus menjadi seorang penyair, tetapi jika dia tidak dapat mendokumentasikan, sejujurnya saya tidak ingin dia ada di tim saya. Orang seperti itu adalah kewajiban jangka panjang.

5

Lebih penting lagi, bagaimana saya meyakinkan mereka bahwa menulis dokumen akan menghemat waktu dan frustrasi kita di masa depan?

Apakah itu berhasil?

Ada dua jenis dokumentasi:

Dokumentasi yang bermanfaat

Dokumen cara menggunakan produk jadi, API, alamat IP apa atau nama URL server kami, dll. Pada dasarnya, semua yang digunakan berat dan setiap hari. Informasi yang salah akan ditemukan dengan cepat dan akan diperbaiki. Perlu ditemukan mudah dan mudah diedit (mis. Wiki online).

Dokumentasi tidak berguna

Dokumentasi yang sering berubah, sangat sedikit orang yang tertarik dan tidak ada yang tahu di mana menemukannya. Seperti keadaan fitur yang sedang diimplementasikan. Atau dokumen persyaratan dalam dokumen kata yang disembunyikan di suatu tempat di SVN, diperbarui 3 tahun lalu. Dokumentasi ini akan membutuhkan waktu untuk menulis, dan waktu untuk mengetahui bahwa itu salah nanti. Anda tidak dapat mengandalkan jenis dokumentasi ini. Itu tidak berguna. Itu buang-buang waktu.

Programmer tidak suka menulis atau membaca dokumentasi yang tidak berguna. Tetapi jika Anda dapat menunjukkan kepada mereka dokumentasi yang bermanfaat, mereka akan menulisnya. Kami mendapatkan kesuksesan besar dalam proyek terakhir saya ketika memperkenalkan Wiki di mana kami dapat menulis semua informasi yang sering kami butuhkan.


4

Saya akan mengatakan bahwa alasan utama adalah kurangnya kemauan dan kurangnya pemahaman tentang fungsi dokumentasi. Ada beberapa kelas dokumentasi yang perlu dipertimbangkan:

Dokumentasi Produk / Rilis

Ini adalah apa pun yang sesuai dengan produk 'jadi' Anda. Ini lebih dari sekadar manual, ini READMEs, Change Logs, CARA-TOs dan sejenisnya. Secara teori, Anda bisa lolos dengan tidak menulis ini, tetapi Anda berakhir dengan produk yang orang tidak ingin gunakan, atau beban dukungan yang tidak perlu mahal.

Dokumentasi API

Ini menggambarkan sesuatu yang seharusnya relatif statis. Karena banyak konsumen mungkin mengkode ke API Anda, itu harus cukup stabil sehingga beberapa prosa yang menggambarkan bagaimana menggunakannya memiliki nilai. Menjelaskan parameter apa yang didukung, berapa nilai baliknya dan kesalahan apa yang dilemparkan akan memungkinkan pengguna lain untuk memahami API Anda pada tingkat abstraksi yang tepat - antarmuka ( bukan implementasi).

Komentar Kode

Pendapat industri tentang komentar tampaknya sedang berubah, saat ini. Ketika saya pertama kali mulai coding secara profesional, komentar adalah sine qua non ketika datang untuk menulis kode. Sekarang, fesyen adalah menulis kode yang begitu jelas, komentar tidak perlu. Saya akan menebak bahwa ini adalah, sebagian, karena fakta bahwa banyak bahasa modern ditulis pada tingkat yang lebih tinggi dan itu jauh lebih mudah untuk menulis kode yang dapat dibaca di Jawa, JavaScript, Ruby, dll. Daripada di assembler , C, FORTRAN, dll. Dengan demikian, komentar memiliki nilai yang jauh lebih besar.

Saya masih percaya bahwa ada nilai dalam komentar yang menggambarkan maksud dari bagian kode, atau beberapa detail tentang mengapa algoritma tertentu dipilih daripada yang lebih jelas (untuk menghindari roh-roh refactoring yang terlalu bersemangat dari 'memperbaiki' kode yang tidak ' t sebenarnya perlu diperbaiki).

Sayangnya, ada banyak keegoisan, rasionalisasi dan delusi diri yang terlibat dalam keputusan programmer untuk tidak mendokumentasikan. Kenyataannya adalah bahwa, seperti kode, audiens utama untuk dokumentasi adalah orang lain. Dengan demikian, keputusan untuk menulis (atau tidak menulis) dokumentasi, di tingkat mana pun, adalah keputusan yang harus dibuat di tingkat tim. Untuk tingkat abstraksi yang lebih tinggi, mungkin lebih masuk akal untuk meminta seseorang, selain pengembang, untuk melakukannya. Adapun dokumentasi di tingkat komentar, mencapai kesepakatan tentang maksud dan maksud komentar harus disepakati bersama, terutama dalam kemampuan campuran dan tim pengalaman. Tidak ada gunanya memiliki pengembang senior menulis kode yang tidak bisa didekati oleh pengembang junior. Beberapa dokumentasi yang ditempatkan dengan baik dan ditulis dengan baik dapat memungkinkan tim untuk beroperasi jauh lebih efektif


1
+1 untuk "audiens utama untuk dokumentasi adalah orang lain". Terlalu banyak programmer tidak benar - benar menghargai komunikasi dengan orang lain. (Itu juga sebabnya mereka akan kesulitan untuk maju dalam senioritas.)
Donal Fellows

4

Ini dua sen saya.

  1. Agile Manifesto menyatakan "Bekerja dengan perangkat lunak dari dokumentasi yang komprehensif" dan tidak semua orang membaca untuk mencapai "Yaitu, sementara ada nilai dalam item di sebelah kanan, kami lebih menghargai item di sebelah kiri."

  2. Sayangnya itu umum untuk https://en.wikipedia.org/wiki/Code_and_fix dan dokumentasi tidak berfungsi dengan model ini (Ini menjadi tidak sinkron).

  3. Industri pengembangan perangkat lunak tidak diatur dengan baik. Tidak ada persyaratan hukum untuk menulis dokumentasi.

  4. Kode mendokumentasikan diri adalah tren saat ini.

Karena itu, saya pikir ada banyak dokumentasi yang bagus di luar sana.


(1) " Kami lebih menghargai hal-hal di sebelah kiri ... " tidak menyiratkan bahwa kami sama sekali tidak peduli dengan sisi kanan. (2) " 4.Kode yang mendokumentasikan diri sendiri adalah tren saat ini " Jika dokumentasi tidak diperlukan, mengapa kemudian orang pertama dan terutama mengeluh tentang dokumentasi yang buruk / hilang? (3) Waktu yang dihemat seorang pengembang dengan tidak mendokumentasikan pekerjaannya dihabiskan oleh setiap pengembang yang membutuhkan informasi, karena ia harus memindai 5.000 baris kode dokumentasi diri alih-alih dokumentasi 5 halaman. Efisiensi adalah sesuatu yang lain, tapi hei, kami gesit!
JensG

2

Dokumentasi membutuhkan waktu, dan saya menduga banyak pengembang memiliki terlalu banyak perselisihan dengan dokumentasi yang lebih buruk daripada tidak berguna. Mereka mendapatkan ide bahwa tidak hanya mendokumentasikan akan membuat mereka kesulitan dari manajer mereka (orang yang sama yang terus memotong bagian QA dari jadwal), tetapi itu tidak akan membantu siapa pun, termasuk mereka.

Sedikit dokumentasi yang setengah layak merupakan investasi di masa depan. Jika Anda tidak peduli dengan masa depan (karena Anda tidak berpikir melampaui gaji berikutnya, atau karena Anda pikir itu tidak akan menjadi masalah Anda), maka pemikiran untuk melakukan dokumentasi sangat menyakitkan.


2

Banyak dari tanggapan lain mengabaikan titik bahwa setidaknya ada dua jenis dokumentasi: satu set untuk pengembang lain, dan satu set yang berbeda untuk pengguna akhir. Tergantung pada lingkungan Anda, Anda mungkin juga memerlukan dokumentasi tambahan untuk administrator sistem, penginstal, dan staf help desk. Setiap target audiens memiliki kebutuhan dan tingkat pemahaman yang berbeda.

Pertimbangkan pengembang khas (stereo-): Ia adalah seorang pembuat kode berdasarkan pilihan. Dia telah memilih karier di mata publik dan menghabiskan berjam-jam di belakang keyboard berkomunikasi terutama dengan dirinya sendiri. Proses dokumentasi adalah bentuk komunikasi dan keterampilan yang diperlukan untuk menghasilkan dokumentasi yang baik bertentangan dengan keterampilan yang diperlukan untuk menghasilkan kode yang baik.

Penulis dokumentasi yang baik dapat berkomunikasi dalam berbagai bahasa: bahasa pengguna, bahasa manajemen, bahasa staf pendukung, bahasa pengembang. Adalah tugas seorang penulis dokumentasi untuk memahami apa yang dikomunikasikan oleh seorang pembuat kode dan menerjemahkannya ke dalam bentuk yang dapat dipahami oleh semua kelompok lain.

Ketika Anda mengharapkan pembuat kode untuk mengembangkan keterampilan yang diperlukan untuk menjadi komunikator yang baik (tertulis atau tidak) jumlah waktu yang dihabiskan untuk mengasah keterampilan dasar (pengkodean!) Berkurang. Semakin jauh ia mendapatkan dari zona nyamannya (coding dan berkomunikasi dengan coders lain), semakin banyak waktu dan energi yang dibutuhkan untuk melakukan tugas dengan baik. Anda dapat mengharapkan pembuat kode profesional untuk berfokus pada kompetensi intinya, dengan mengorbankan semua yang lain.

Untuk alasan ini, dokumentasi (dengan pengecualian komentar kode sebaris) sebaiknya diserahkan kepada komunikator, bukan coders.


4
Oh, pish. Semakin banyak hal yang Anda pelajari untuk dilakukan dengan baik, semakin baik Anda belajar untuk melakukan hal-hal dengan baik. Sama seperti orang-orang yang tahu beberapa program bahasa lebih baik daripada orang-orang yang hanya tahu satu (karena mereka tahu lebih banyak cara untuk memikirkan masalah), mampu menulis dan bahkan memvisualisasikan secara grafis memberi Anda lebih banyak alat untuk berpikir dan menyelesaikan masalah. Keterampilan yang Anda butuhkan untuk dapat menggambarkan apa yang terjadi adalah keterampilan yang sama dengan yang Anda butuhkan untuk mengetahui apa yang harus terjadi.
Amy Blankenship

1
Saya ingin pengembang lain menjadi atau menjadi komunikator yang terampil. Sebagian besar pemrograman yang kita lakukan (setidaknya dalam perangkat lunak bisnis) tidak memerlukan keahlian pengkodean terasah tertinggi yang absolut. Dibutuhkan keterampilan komunikasi orang-ke-orang yang jauh lebih baik sehingga pengembang di masa depan memahami apa yang ditulis. Semakin baik pengembang dapat berkomunikasi, terutama kepada orang-orang yang tidak akan pernah mereka temui, semakin baik mereka akan dipikirkan dalam jangka panjang, dan tidak mungkin untuk kode pintar.
Kevin Rubin

2

Membaca kode menunjukkan cara kerjanya. Tidak bisa menjelaskan alasannya : Anda perlu komentar.

Membaca kode menunjukkan kepada Anda nama metode, dan jenis parameter. Itu tidak dapat menjelaskan semantik, atau maksud sebenarnya dari penulis: Anda perlu komentar.

Komentar tidak menggantikan pembacaan kode, mereka menambahnya.


4
+1 untuk sentimen. Tapi ini bukan jawaban untuk pertanyaan itu; Anda tampaknya merespons sesuatu yang lain di sini selain dari pertanyaan aktual yang diajukan.
bignose

2

Dokumentasi tidak dieksekusi seperti kode. Akibatnya sering ada loop umpan balik yang tidak efektif untuk memverifikasi bahwa dokumentasi sudah ada dan lengkap. Ini adalah alasan yang sama dengan komentar kode yang cenderung membusuk.

Donald Knuth mempromosikan Programate Literate sebagai cara untuk meningkatkan kualitas perangkat lunak, secara efektif menulis dokumentasi dengan kode. Saya telah melihat beberapa proyek yang telah menggunakan pendekatan ini dengan cukup efektif.

Secara pribadi saya mencoba untuk tetap berpegang pada tren modern menjaga API publik dari kode Anda dapat dibaca sebagai mungkin, dan menggunakan tes unit untuk mendokumentasikan penggunaan untuk pengembang lain. Saya pikir ini adalah bagian dari ide yang lebih besar untuk membuat API Anda menjadi bentuk yang dapat dieksplorasi dan ditemukan. Saya pikir pendekatan ini adalah bagian dari apa yang HATEOAS coba capai dengan layanan web.


Untuk menjustifikasi pilihan saya untuk generasi dokumentasi otomatis, saya datang dengan formula tiruan untuk menunjukkan bagaimana inersia manusia adalah biang keladi dari semua komentar yang membusuk. Ketika memperluas argumen, saya menemukan bahwa menciptakan metode yang memberikan keuntungan aktual bagi pengembang, seperti pembuatan diagram sebagian otomatis dari komentar meta dalam kode sumber, cenderung diperbarui setiap kali, pengembang mencoba memahami kode tersebut. BTW, lebih sering daripada tidak pengembang ini hanya "masa depan saya".
wolfmanx

0

Poin kecil, tetapi yang tampaknya penting dengan beberapa pengembang yang menulis sedikit dokumentasi yang menjengkelkan: mereka tidak bisa mengetik. Jika Anda memiliki perkiraan sistem 10 jari, Anda cenderung menulis lebih banyak dokumentasi hanya karena mudah. Tetapi jika Anda terjebak dengan berburu dan mematuk Anda tersesat. Jika saya akan bertanggung jawab untuk mempekerjakan ini sebenarnya adalah sesuatu yang saya akan periksa.


0

Orang yang tidak suka membaca dokumentasi tidak suka menulis dokumentasi. Banyak programmer akan melakukan semua yang mereka bisa untuk menghindari membaca dokumen secara menyeluruh.

Jangan fokus pada tulisan, fokus pada membaca. Ketika programmer membaca dokumentasi dan mengasimilasi hal-hal dari itu, mereka akan melihat nilainya dan lebih cenderung untuk menulis beberapa.


-1

Ketika saya memulai pekerjaan saya saat ini dan mengambil alih proyek perangkat keras + perangkat lunak dari orang-orang yang sebelumnya telah mengerjakannya, saya diberi seratus atau lebih halaman dokumen kata ms yang menjelaskan sistem. Pasti butuh berhari-hari untuk diproduksi. Saya melihatnya mungkin dua kali. Meskipun ada banyak sekali informasi di sana, jarang menjawab pertanyaan aktual yang saya miliki tentang sistem, dan bahkan ketika itu terjadi, lebih cepat untuk melihat kode.

Setelah pengalaman yang cukup seperti itu, Anda baru mulai berpikir, mengapa repot-repot? Mengapa menghabiskan waktu Anda menjawab pertanyaan yang tidak pernah ditanyakan orang? Anda mulai menyadari betapa sulitnya memprediksi informasi apa yang akan dicari orang dalam dokumentasi; itu pasti diisi dengan fakta-fakta yang ternyata menjadi tidak berguna, tidak jelas atau jelas, dan tidak memiliki jawaban untuk pertanyaan yang paling mendesak. Ingat, menghasilkan dokumentasi yang bermanfaat adalah upaya memprediksi perilaku manusia. Sama seperti desain antarmuka pengguna tidak mungkin berhasil sebelum itu telah melalui beberapa iterasi pengujian dan debugging, jadi naif untuk berpikir bahwa mungkin untuk menulis dokumentasi yang berguna hanya berdasarkan harapan bagaimana orang akan menafsirkan sistem, dan apa peran dokumentasi dan bahasanya akan bermain dalam interpretasi itu.

Saya cenderung berpikir bahwa sebagian besar tekanan untuk menulis dokumentasi berasal dari fakta bahwa itu adalah pekerjaan yang tidak menyenangkan dan orang-orang suka saling menipu untuk melakukan pekerjaan yang tidak menyenangkan ("Anda belum makan tong filboid Anda!").

NAMUN

Saya tidak berpikir dokumentasi itu, dalam segala hal, tidak ada harapan. Saya pikir itu tidak ada harapan terutama ketika orang melihat dokumentasi sebagai beban tambahan yang harus dipenuhi sebelum pekerjaan selesai, sebagai pekerjaan pembersihan terakhir yang harus dilalui, dan sebagai sebuah kotak untuk diperiksa. Dokumentasi adalah sesuatu yang harus Anda kerjakan dalam aspek-aspek hari Anda yang selalu Anda lakukan. Saya pikir email adalah cara yang sangat baik untuk melakukan dokumentasi. Saat Anda menambahkan fitur baru, tulis beberapa orang email cepat yang mengatakan apa itu. Saat menggambar skema baru, buat PDF dan kirimkan ke siapa pun yang mungkin tertarik. Kelebihan email adalah:

  1. Orang biasanya memeriksa email, sedangkan tidak ada yang mengarungi folder bernama "doc".

  2. Email ada dalam konteks, dikelilingi oleh email lain yang membahas fitur dan fitur terkait dan apa pun yang terjadi pada saat itu.

  3. Email pendek dan fokus dan memiliki baris subjek.

  4. Email memungkinkan orang-orang yang peduli untuk langsung bertanya,

  5. Email sangat mudah dicari, karena orang menggunakannya untuk semuanya dan klien email telah naik sedikit selama bertahun-tahun.

  6. Jika ada dalam email, setidaknya satu orang lain tahu di mana menemukannya.

Secara teori seharusnya terlihat bahwa komentar dalam kode juga harus "aspek hari Anda yang selalu Anda lakukan", tetapi jujur ​​saja, saya tidak pernah membaca komentar dalam kode. Saya tidak yakin mengapa, tapi itu tidak terlalu membantu, mungkin karena ada kekurangan konteks, yang dipecahkan email.


kecuali untuk # 4 ("orang yang peduli langsung bertanya"), tidak ada manfaat email yang Anda cantumkan berhasil bagi saya. 1: Orang-orang cenderung mengabaikan email, ketika ada banyak itu 2: Email sering cenderung konteks kehilangan, mengubur dalam sisi-isu dan overquoting 3: Email terlalu sering lama / besar dan cenderung fokus kalah sebagai diskusi masuk ke lebih banyak masalah sampingan dan baris subjek sering tidak relevan / usang ("Re: WTF terjadi di server hari ini?") ...
gnat

... 5: Pencarian email sangat dikompromikan oleh kemampuan untuk menghapus email, fitur yang dimiliki setiap mailer yang baik dan semua pengguna email yang aktif dengan baik, menggunakan banyak 6: lihat 5, jika email dihapus, tidak ada yang akan dapat menemukannya (satu-satunya hal yang dapat saya andalkan adalah mencari email yang saya kirim dan ini hanya karena saya berusaha sangat keras untuk tidak menghapusnya). Selain pujian email (yang terlihat sangat tidak adil bagi saya), Anda membuat beberapa poin bagus
Agak

@gnat Saya kira itu mungkin berbeda perusahaan ke perusahaan tentang menghapus. Di perusahaan saya, kami menyimpan semua email, ditambah arsip semua email dari karyawan masa lalu, dan setiap kali orang baru memulai tugas, kami meneruskan orang itu ke semua email terkait. Saya kira perbedaan dalam gaya.
Owen

yeah, itu tergantung banyak pada gaya / budaya. Sementara "memerangi penghapusan" tentu saja dapat dilakukan (dan bahkan secara teknis sederhana untuk dicapai dengan mengekspor utas mail ke beberapa server), hal-hal seperti menjaga mereka tetap fokus, baris subjek yang relevan, mengutip terbatas pada batas wajar adalah hal yang sangat budaya, membutuhkan usaha yang cukup banyak dan tekad (dan dukungan manajemen) untuk mempertahankan ... Dibandingkan dengan upaya ini, dan terutama dengan kebutuhan untuk pembelian mgmt, mempertahankan hal-hal seperti wiki / kode komentar / folder dokumen mungkin menjadi lebih mudah
gnat
Dengan menggunakan situs kami, Anda mengakui telah membaca dan memahami Kebijakan Cookie dan Kebijakan Privasi kami.
Licensed under cc by-sa 3.0 with attribution required.