Apa sebenarnya yang dimaksud dengan 'Dokumentasi'?

12

Ketika kita mengatakan 'dokumentasi' untuk produk perangkat lunak, apa yang termasuk dan apa yang tidak termasuk?

Misalnya, pertanyaan terbaru yang diajukan jika komentar dianggap dokumentasi?

Tetapi ada banyak bidang lain yang juga merupakan pertanyaan yang valid, beberapa lebih jelas daripada yang lain:

  • Manual (jelas)
  • Catatan rilis?
  • Tutorial
  • Komentar
  • Ada yang lain

Di mana garis digambar. Misalnya, jika 'tutorial' adalah dokumentasi, apakah dokumentasi 'video tutorial', atau apakah itu sesuatu yang lain?

Secara umum, sesuatu dalam perangkat lunak tidak 'selesai' sampai diimplementasikan, diuji dan didokumentasikan. Karenanya pertanyaan ini, hal apa yang harus kita pertimbangkan sebagai bagian dari dokumentasi untuk mempertimbangkan sesuatu yang 'dilakukan'.

Pertanyaan menginspirasi dari umpan balik pelanggan baru-baru ini di konferensi kami yang menunjukkan bahwa dokumen kami membutuhkan lebih banyak 'sampel', yang sebelumnya kami tidak sebaik mempertimbangkan sebagaimana seharusnya.

Pemirsa: Pengembang perangkat lunak menggunakan basis data kami, bahasa pemrograman dan perkakas terkait (seperti klien admin untuk mengatakan DB)

documentation terminology Dan McGrath
sumber
2
Komentar tentang downotes selalu dihargai. Sayangnya angka tidak memberikan banyak kritik konstruktif untuk memahami di mana orang telah menyimpang :)
Dan McGrath
1
Dokumentasi perangkat lunak atau dokumentasi kode sumber adalah teks tertulis yang menyertai perangkat lunak komputer. Entah itu menjelaskan bagaimana ia beroperasi atau bagaimana menggunakannya, dan dapat berarti hal yang berbeda bagi orang-orang dalam peran yang berbeda. - "Dapat berarti hal yang berbeda bagi orang dalam peran yang berbeda" adalah kalimat kunci di sini, apa audiens Anda? (Belum memilih, tapi saya menduga ketidakjelasan dan sifat pertanyaan yang terbuka adalah yang harus disalahkan).
yannis
Terkait: Apakah Komentar berupa Dokumentasi
Dinamis
2
Pertanyaan ini menjerit bagi seseorang untuk menggambar diagram Venn.
MathAttack

Jawaban:

6

Tujuan dari dokumentasi adalah untuk mendeskripsikan dan menjelaskan produk perangkat lunak, sehingga Anda dapat mendefinisikan dokumentasi untuk menjadi kumpulan artefak yang berkontribusi pada deskripsi atau penjelasan itu. Anda mungkin tidak akan mempertimbangkan tindakan terkait sebagai bagian dari dokumentasi: misalnya kursus pelatihan selama seminggu bukan dokumentasi tetapi materi kursusnya; obrolan papan tulis lima menit bukan dokumentasi tetapi gambar papan tulis itu.

Mengingat tujuan (menjelaskan perangkat lunak), dokumentasi selesai ketika pelanggan puas dengan penjelasan : sama seperti perangkat lunak selesai ketika pelanggan puas dengan perangkat lunak. Ingatlah bahwa pelanggan untuk dokumentasi tidak selalu sama dengan pelanggan yang membayar untuk perangkat lunak: personel pendukung, penguji, tenaga penjualan, dan yang lainnya semua akan memerlukan pemahaman tentang apa yang dilakukan perangkat lunak dan cara kerjanya.

Ini membantu memahami di mana batas Anda untuk apa yang harus dimasukkan dalam dokumentasi terletak. Menggunakan "pembaca" sebagai istilah praktis, meskipun kami menerima bahwa video atau audio dapat dimasukkan: apa pun yang membantu pembaca mendapatkan informasi yang mereka butuhkan tentang perangkat lunak adalah dokumentasi yang dapat mereka gunakan, sedangkan yang lain tidak. Jika pelanggan Anda membutuhkan walk-through rinci dari semua kasus penggunaan mereka, maka itu harus menjadi bagian dari dokumentasi. Pengembang Anda mungkin memerlukan kode sumber, informasi tentang repositori kontrol versi Anda dan instruksi pembuatan: itulah dokumentasi untuk mereka, tetapi seperti yang dijelaskan di atas, itu tidak akan menjadi bagian dari dokumentasi pelanggan.


sumber
Saya hanya akan mempertimbangkan materi pelajaran sebagai dokumentasi jika materi tersebut diproduksi / didistribusikan oleh tim yang sama (dalam arti luas) seperti yang dihasilkan perangkat lunak. Kursus pihak ketiga yang benar-benar bukan dokumen.
Donal Fellows
Tentu mereka. Dokumentasi pihak ketiga adalah dokumentasi meskipun itu tidak di bawah kendali Anda (dan bukan tanggung jawab Anda untuk menghasilkan): ia melayani tujuan pembaca untuk menjelaskan hal-hal kepada mereka. Jika itu masalah bagi Anda bahwa orang-orang menulis dokumentasi yang tidak di bawah kendali Anda, Anda harus menyingkirkan kebutuhan untuk dokumentasi itu.
2

Saya pikir Anda mengambil bagian yang salah dari percakapan Anda di sebuah konferensi. Metodologi pengembangan perangkat lunak modern menganjurkan bahwa tim pengembangan harus bekerja erat dengan pelanggannya (atau pemilik produk yang bertindak sebagai proxy pelanggan). Untuk semua pekerjaan yang disampaikan, definisi "selesai" adalah sesuatu yang dinegosiasikan antara tim dan pelanggannya dan dilakukan secara berulang ketika perangkat lunak sedang dikembangkan.

Masalah yang Anda hadapi adalah bahwa Anda memiliki keterputusan antara apa yang Anda anggap pelanggan butuhkan dan apa yang mereka harapkan Anda berikan sehingga pada akhirnya Anda mendapatkan kejutan "hei di mana semua sampel".

Sejauh, apa itu dokumentasi ... well, itu hampir semua yang Anda daftarkan dan mungkin beberapa hal lagi yang tidak Anda daftarkan. Tetapi tidak ada yang bisa memberi tahu Anda berapa banyak dokumentasi yang dibutuhkan proyek Anda. Setiap proyek berbeda dan tergantung pada tim Anda, pemilik produk Anda dan pelanggan Anda untuk menentukan tingkat dan jenis dokumentasi yang diperlukan untuk proyek Anda.

Beberapa faktor yang akan berperan:

  • Apakah Anda mengembangkan perangkat lunak v1.0 dan mereka pindah ke proyek lain atau apakah ini proyek jangka panjang yang sedang berlangsung? Komentar / dokumen desain menjadi jauh lebih penting dalam kasus terakhir. Di sisi lain jika pelanggan Anda adalah toko donat ibu-dan-pop dan Anda menulis sebuah situs web untuk mereka yang tidak akan pernah Anda lihat ... well, saya kira dokumentasi kode bagus tapi tidak terlalu penting.
  • Apakah Anda mengembangkan game atau perangkat lunak seluler yang mengendalikan monitor detak jantung di rumah sakit. Coba tebak mana yang akan memiliki definisi "selesai" yang memiliki lebih banyak dokumentasi?
  • Apakah pelanggan Anda tipikal pengguna akhir atau mereka pengembang lain? Apakah Anda memiliki API / SDK yang Anda paparkan?
  • Apa tingkat keahlian pelanggan Anda? Ini memengaruhi pilihan video tutorial vs. materi tertulis vs. beberapa jenis aplikasi tutorial interaktif
  • Apakah pelanggan Anda peduli dengan apa yang berubah dari versi ke versi. Beberapa melakukannya. Kebanyakan tidak. Untuk beberapa orang itu adalah hukum (atau dekat dengan itu) untuk peduli.
DXM
sumber
Mengatakan saya mengambil bagian yang salah dari percakapan berdasarkan pada satu Q adalah sedikit banyak kesimpulan untuk ditarik dari satu Q :) Saya baru di perusahaan ini dan membantu dengan perbaikan. Memberi nomor 'pelanggan' kami di 10'000s + pengembang (kami menulis database) bernegosiasi dengan mereka semua agak sulit (meskipun, saya mencoba menjalankan kelompok fokus, dewan penasihat, dll). Saya tidak setuju dengan jawaban Anda, tetapi saya hanya mencari apa yang bisa / tidak mempertimbangkan dokumentasi untuk bagian percakapan ini sehingga saya dapat memiliki titik data untuk memulai dari itu bukan hanya pendapat saya sendiri.
Dan McGrath
@DanMcGrath: maaf, saya cenderung menggosok PM, termasuk saya sendiri, dengan cara yang salah :) Terlepas dari asumsi yang saya simpulkan dari Q Anda, saya masih akan mempertahankan bahwa "apapun" yang sesuai dengan kode dapat dianggap sebagai "dokumentasi". Jika saya jadi Anda, alih-alih bertanya "apa yang bisa menjadi dokumentasi" dan menyusun daftar lengkap semua hal (saya dulu punya serbet referensi dengan diagram UML di atasnya), saya akan kembali ke basis pelanggan saya dan bertanya mereka apa yang mereka butuhkan. Jika tidak ada yang mengatakan "Saya ingin tutorial video", mengapa saya harus menghabiskan siklus otak bahkan mempertimbangkan itu?
DXM
Tidak masalah DXM. Saya hanya seorang PM baru juga, baru-baru ini mencukur saya memotong kode (sebagian). Saya lebih tertarik untuk melihat apakah seseorang kembali dengan sesuatu yang saya tidak anggap sebagai konsep atau sebagai artefak untuk dipertimbangkan. Saya penggemar bertanya 'apa masalah Anda' dan meminta tim kami menyelesaikannya secara kolaboratif dengan pelanggan, dan bukannya bertanya 'apa yang Anda ingin kami lakukan'. Di sepanjang garis yang sama dengan ['Kami ingin bergerak lebih cepat' -> Kami membuat mobil] vs ['Kami ingin Anda memberi kami kuda lebih cepat']. Memiliki kami banyak info yang membantu secara kolektif menemukan kemungkinan solusi terbaik.
Dan McGrath
2

Dokumentasi adalah hal-hal yang dimaksudkan untuk dibaca tanpa mengubahnya.

Saya pikir Anda tidak dapat salah dengan definisi berbasis tujuan ... tetapi hanya jika Anda mendefinisikan tujuan dengan benar.

  • Mendefinisikan tujuan dokumentasi dengan benar tidak cukup sederhana. Perbedaan langsung (naif jika Anda inginkan) yang secara alami terlintas dalam pikiran adalah bahwa dokumentasi adalah segala yang dimaksudkan untuk membaca - sementara, untuk perbandingan, kode adalah segala sesuatu yang dimaksudkan untuk eksekusi komputer . Kedengarannya bagus di permukaan bukan? tetapi ternyata benar-benar jelek sekali Anda menggali lebih dalam.
     
    Masalahnya, kode yang baik mempertimbangkan masalah keterbacaan akun, bersama dengan kebenaran eksekusi - ini membuat perbedaan "keterbacaan" sangat tidak berguna dalam mendefinisikan dokumentasi.
     
    Sangat sampel yang Anda sebutkan menunjukkan apa yang salah dengan itu. Klien biasanya mengharapkan ini ditulis dengan jelas danjalankan dengan benar. Mengompromikan keterbacaan atau kebenaran dapat membawa air terjun dari keluhan pelanggan. Perbedaan naif tidak membantu untuk mencari tahu apakah sampel adalah kode atau dokumentasi.
     
    Menggunakan perbedaan naif akan menjadi lebih berantakan jika Anda membayangkan bekerja dengan open source . Anda mengunduh, membuat, dan menjalankannya - Anda tidak membacanya, hanya kodenya saja? Tunggu, entah bagaimana ada yang salah dan Anda mendapatkan kode untuk membaca apa yang terjadi di sana ... hei Anda baca tidak jalankan - apakah dokumentasi ini sekarang? Dan, akhirnya, Anda menemukan bug di sumbernya dan memperbaikinya - sekarang ini benar-benar kode, itu bukan sesuatu yang biasa disebut dokumentasi, tidak peduli seberapa hati-hati Anda membacanya untuk melakukan perbaikan itu.

Untuk 'sampel' yang akan Anda berikan, perbedaan baca-tidak-modifikasi mungkin menjadi sangat penting.

Lihat, jika beberapa sampel gagal saat dijalankan tidak berubah, di lingkungan referensi yang terdokumentasi, itu adalah bug Anda - bug dalam dokumentasi Anda, yang harus Anda terima dan perbaiki, baik.

Sekarang, jika ada masalah dengan sampel atau lingkungan yang dimodifikasi, itu bukan kesalahan Anda lagi - maksud saya tidak ada bug dalam dokumentasi, karena dokumen tidak dimaksudkan untuk modifikasi. Apa pun bantuan yang Anda berikan kepada pengguna jika seperti itu, akan jatuh di bawah kategori dukungan, bukan perbaikan bug.

agas
sumber
2

Apa pun yang menjawab pertanyaan "bagaimana saya ..." adalah dokumentasi.

Untuk pengembang, itu berarti spesifikasi persyaratan ("bagaimana saya tahu apa yang harus ditulis"), dokumen desain ("bagaimana cara mengatasi persyaratan saya"), matriks keterlacakan ("bagaimana saya tahu bahwa desain saya menangani semua persyaratan saya"), rencana pengujian ("bagaimana saya tahu kode saya berfungsi"), unit test ("bagaimana saya tahu saya sudah memenuhi persyaratan X"), komentar inline ("bagaimana saya memastikan schlub miskin berikutnya mengerti mengapa saya menulis ini cara "), instruksi penerapan (" bagaimana cara saya mengemas produk ini untuk instalasi "), dll.

Untuk pengguna, itu berarti manual pengguna ("bagaimana saya menggunakan perangkat lunak"), tutorial ("bagaimana saya menggunakan fitur spesifik ini"), catatan rilis ("bagaimana saya tahu bug apa yang telah diperbaiki / fitur bug baru telah ditambahkan "), dll.

John Bode
sumber