Manual - Bagaimana Terkini?

10

Jika Anda memiliki produk yang sudah lama ada di pasaran, tetapi masih dalam pengembangan aktif setiap hari - seberapa sering manual harus diperbarui? Jika pengguna Anda terus-menerus diperbarui ke versi tepi berdarah karena fakta bahwa organisasi Anda merasa cocok bahwa perbaikan bug terbaru selalu dalam versi yang dikirimkan. Artinya, Anda dapat memperbaiki bug suatu hari dan hari berikutnya ia sedang membanjiri produksi.

manuals production Brian
sumber
1
Apakah kita berbicara manual yang dicetak atau online? Setidaknya ada beberapa bentuk berbeda yang bisa diambil.
JB King
Manual online (PDF)
Brian

Jawaban:

4

Saya akan memperbarui manual:

  1. Untuk setiap rilis utama, dan
  2. Ketika fitur-fitur baru yang penting menjadi stabil dan cukup matang sehingga Anda tahu mereka tidak akan berubah setiap lima menit.
Robert Harvey
sumber
3

perbarui manual (PDF) kapan saja perubahan kode akan mengubah instruksi dalam manual - cukup buat memperbarui bagian manual dari proses rilis

jika pengguna bergantung pada manual untuk memberi tahu mereka cara menggunakan produk, dan produk berubah, maka masuk akal bahwa bagian yang relevan dari manual juga harus berubah

Steven A. Lowe
sumber
1
jadi jika tidak ada penulis teknis pada staf, lalu perbarui sendiri?
Brian
@ 0A0D - jika Anda tidak memiliki penulis, Anda tidak punya banyak pilihan, kecuali ada staf penguji atau pendukung yang dapat melakukannya.
JeffO
1
Saya memiliki dokumen 'file sumber' sebagai bagian dari proyek saya. Mereka selalu diperbarui pada saat yang sama dengan kode. Mereka diversi dengan rilis dan dikelola menggunakan alat managmnet sumber yang sama dengan sisa file proyek (pergi Mercurial!). Saya memiliki satu set manual standar yang cukup untuk mengerjakan sebuah proyek dan ini semua dikelola dengan cara yang sama (panduan pengguna, konfigurasi / panduan instalasi, catatan rilis dan dokumen referensi / teknis kami sendiri).
2

Di tahun 2010 apakah kita masih mengacu pada dokumentasi cetak? Mengapa? ;)

Dalam keseriusan semua, dokumentasi (baik bantuan aplikasi "F1", PDF, atau dokumentasi online) harus menjadi bagian dari setiap rilis. Tidak ada alasan. Sesederhana itu untuk "menerbitkan." Faktanya, IMO, tidak ada alasan untuk tidak memperbarui dokumentasi secara teratur (online dan PDF), bahkan di antara rilis, segera setelah masalah diketahui dan diperbaiki. Tidak perlu level QA yang sama - bahkan tidak mendekati.

Mark Freedman
sumber
2

Saya berasumsi Anda berbicara tentang dokumentasi pengguna akhir. Menulis dokumentasi itu menyebalkan di @ $$ dan sementara saya telah mengembangkan beberapa teknik untuk meyakinkan saya kebalikannya, saya masih memiliki masalah dengan itu. Inilah cara saya mencoba mengelolanya:

Integrasikan pembaruan dokumentasi dalam DoD Anda ( Definisi selesai )

Ini akan memastikan bahwa dokumentasi Anda akan diperbarui di akhir setiap penyelesaian cerita pengguna.

Berikut adalah definisi yang sudah kami buat. Saya mencoba mempertahankan format aslinya, jadi Anda mendapatkan idenya. Ini adalah halaman A4 yang diletakkan di papan tulis.

---------- 8 <------------ Potong Di Sini ------------ 8 <----------

Yang tidak bisa ditawar

Definisi "Selesai"

  • Kode dengan cakupan uji unit 80%, dilakukan dalam repositori

  • Tangkapan layar jika berlaku (1024x728, 395x281, 170x121 & 729x329)

  • Deskripsi fitur jika berlaku (50 karakter, 100 karakter)

  • Dokumentasi pengguna akhir lengkap

  • File baru apa yang diperbarui dengan benar

---------- 8 <------------ Potong Di Sini ------------ 8 <----------

Tentu saja Anda dapat menambahkan proses peninjauan dalam dokumentasi. Kami mengalaminya karena tidak ada di antara kami yang berbahasa Inggris.

Salah satu keuntungan dari Definisi Selesai seperti ini adalah bahwa produk Anda berpotensi dapat dikirim pada akhir setiap penyelesaian cerita pengguna.

Gunakan teknik ini dalam kombinasi dengan yang ini .


sumber
1

Di organisasi saya, kami biasanya memiliki 3 jenis rilis:

  1. Rilis Rekayasa - pada dasarnya perbaikan terbaru untuk beberapa pelanggan tertentu atau beberapa fitur yang hanya diminta oleh pelanggan tertentu secara langsung.
  2. Rilis Minor - perbaikan bug, dukungan tambahan
  3. Rilis Utama - dukungan fitur baru dll.

Menurut definisi, Rilis Utama harus memiliki dokumentasi yang relevan baik online maupun offline. Sistem pelacakan kami memastikan bahwa dokumentasi merupakan bagian dari daftar periksa.

Rilis minor hanya memerlukan dokumentasi tentang hal baru yang telah ditambahkan pada tingkat persepsi pengguna. Jadi, jika Anda sudah memasukkan heuristik lain yang mungkin mengurangi kompleksitas waktu dalam beberapa skenario tertentu, itu mungkin atau mungkin bukan panggilan penting untuk memasukkannya ke dalam pdf.

Rilis teknik bisa dilakukan tanpa dokumentasi. Beberapa catatan penggunaan informal harus cukup baik untuk memulai.

Fanatic23
sumber
0

Dokumentasi harus disinkronkan dengan perangkat lunak apa pun yang Anda kirim ke pelanggan. Ketidaksesuaian lain akan memberi Anda masalah. Dan jika Anda tidak memiliki staf penulis, cobalah kontraktor. Setelah Anda menemukan yang Anda sukai, pertahankan dia di punggawa.

SnoopDougieDoug
sumber