Manajemen Penulisan Spec

9

Saya tidak bisa membayangkan menulis perangkat lunak tanpa spesifikasi. Tidak peduli seberapa samar atau tingkat tinggi itu, spec penting untuk menjelaskan kepada programmer yang tidak mengerti tentang apa fungsi dari program.

Tetapi masalah dengan spec adalah bahwa ia agak warga negara kelas dua di seluruh siklus pengembangan perangkat lunak; ketika pengembangan mengambil uap, itu diabaikan. Tetapi ketika perselisihan muncul, pengembang dan penguji dan penjualan akan berebut untuk menemukan spesifikasi untuk membenarkan alasan mereka.

Satu skenario atau lebih akan terjadi:

  1. Spek tidak dapat dipulihkan, tidak ada yang tahu di mana spek
  2. Versi spesifikasi yang berbeda muncul dari sumber yang berbeda; dibutuhkan kesulitan besar untuk mengetahui versi yang merupakan versi terbaru, atau apakah ada adalah versi terbaru yang tersedia.
  3. Spesifikasi tidak lengkap, beberapa bagian dari dokumen yang dimaksud hilang.

Jadi manajemen spek itu penting, dan sama pentingnya bahwa setiap orang hanya memiliki Satu Sumber Spek.

Bagaimana Anda mengelola spesifikasi Anda? Saya mencoba membuat semua orang menggunakan Google Documents tetapi semua orang keberatan. Setiap orang terlalu terikat dan terpikat dengan Microsoft Word, yang - menurut mereka - sangat mudah digunakan, sangat mudah untuk memasukkan gambar, sangat mudah untuk mengetik persamaan dan yang lainnya.

Bagaimana meyakinkan mereka bahwa MS Word mengerikan untuk dibagikan?

specifications Graviton
sumber

Jawaban:

6

Bagaimana meyakinkan mereka bahwa MS Word mengerikan untuk dibagikan?

Jangan buang waktu Anda.

Pertama. Spesifikasi harus dalam teks biasa (benar-benar) dan di bawah kendali kode sumber. Gunakan Penurunan harga atau RST atau alat markup ringan lainnya untuk menghasilkan halaman PDF atau HTML. Teks biasa

Kedua. Ambil berbagai sumber. Gabungkan mereka. Tulis dokumen akhir Anda sendiri.

Ketika mereka keberatan, mereka memiliki dua pilihan.

  1. Gunakan Google Documents (atau alat kontrol kode sumber) untuk mengedit versi Anda .

  2. Terus mengirimi Anda perubahan yang Anda edit, saring, dan ubah menjadi dokumen akhir.

Saya lebih suka # 2. Seseorang perlu "memiliki" spec. Dan sekelompok orang (gaya wiki) mengarah ke perdebatan dan perubahan perang dan dokumen sampingan dan percakapan off-line dan sejenisnya.

S.Lott
sumber
1
+1, dan ingat Aturan Kekuatan Terkecil - Siapa pun yang menginginkan versi mewah dalam editor WYSIWYG dapat menyalin salinan yang diberikan.
l0b0
@ l0b0: Tautan bagus.
S.Lott
6

Saya tidak berpikir itu adalah masalah "alat" melainkan masalah "proses" (atau kurangnya proses).

Anda mungkin sudah memiliki proses untuk merilis perangkat lunak (uji unit, uji integrasi, surat rilis, pengiriman, dll), Anda perlu mengimplementasikan proses dokumentasi juga.

  • Siapa yang akan menulis spesifikasi? Siapa yang akan memperbarui atau merawatnya?
  • Siapa yang akan meninjau spesifikasi?
  • Siapa yang akan menyetujui spesifikasi? Arsitek, pemimpin proyek, QA?
  • Bagaimana spesifikasi disimpan?
  • Siapa yang akan memastikan bahwa tidak ada versi usang yang digunakan?
Xavier T.
sumber
2
+1: masalah alat sering merupakan gejala dari masalah proses.
S.Lott
kami memang memiliki proses tetapi orang hanya suka mengeluh bahwa proses tidak bekerja dan memotong sudut bila memungkinkan.
Graviton
@Graviton: masalah utama Anda mungkin karena manajemen tidak dapat melihat penggunaan dokumentasi dan karenanya, jangan menegakkan aturan yang ketat. Jika Anda ingin segala sesuatunya membaik, Anda mungkin harus menunjukkan kepada mereka betapa pentingnya hal itu.
Xavier T.
4

Beberapa jenis kontrol pasti diperlukan.

Itu perlu versi, dan ditandatangani, dan proses ini harus ketat.

Di terlalu banyak tempat, penandatanganan diabaikan, dan ini menyebabkan pertengkaran sanggul.

Lokasi tidak masalah selama itu bisa dilacak

  • Sharepoint
  • drive bersama yang aman dan dicadangkan
  • Saya telah melihat beberapa tempat menggunakan kontrol sumber kode mereka !!

Tetapi yang lebih penting Anda perlu membeli dari semua yang terlibat dan 1 atau 2 orang yang bertanggung jawab untuk mengelola dokumen DAN tanda tangan misalnya. Manajer Proyek.

ozz
sumber
+1, saya sangat menyarankan memindahkan spec doc ke kontrol sumber jika tidak ada yang membantu. Salah satu keuntungannya adalah Anda mendapatkan riwayat versi. Bahkan jika Anda tidak dapat melakukan versi diffs (kecuali jika Anda menemukan plugin yang dapat melakukan diffs pada file Word) Anda masih dapat mengekstrak semua versi dan melihat apa yang berubah. Ini bisa SANGAT berguna dalam sengketa spesifikasi. Sign-off juga sangat bagus. Dan juga pentingnya melibatkan semua orang dalam proses (jadi tidak ada yang bisa mengatakan "kapan itu diputuskan?") Tidak bisa cukup ditekankan.
FrustratedWithFormsDesigner
0

MS Word sangat baik untuk membuat spec. Kami mengelola milik kami di SharePoint, yang juga menangani versi. Jika Anda tidak memiliki SharePoint atau produk manajemen dokumen lainnya, Google Documents OK (sekarang Anda dapat mengunggah file .doc / .docx tanpa mengonversinya ke format Google Documents). Atau seperti yang disarankan orang lain, Anda bahkan dapat menyimpannya di sistem kontrol versi kode sumber (jika orang yang membuat spesifikasi memiliki akses ke sistem itu).

Marcie
sumber
0 
 > How to convince them that MS Word is just terrible for sharing?

Anda tidak dapat dengan mudah membandingkan apa perbedaan dua contoh dalam sistem kontrol versi.

Saya tidak suka spesifikasi kata untuk alasan itu. Tetapi karena ini adalah keputusan politik untuk menggunakan spesifikasi kata, kami memiliki halaman pertama "informasi sejarah" dengan kolom ini:

versi-nomor (terkait dengan verifikasi produk), penulis, tanggal, deskripsi

k3b
sumber