Mengapa Menulis Dokumen Desain Perangkat Lunak Itu Penting

Selamat, Anda adalah pengembang independen yang kompeten. Dari awal Anda yang sederhana, mungkin bekerja sebagai penguji, Anda telah berkembang menjadi pengembang tim, lalu menjadi pengembang senior, dan sekarang Anda telah membuat lompatan lain, yang terbesar dari semuanya, untuk bekerja secara langsung dengan klien.

Tapi di mana transisi lainnya linier, yang terakhir ini eksponensial. Sementara di masa lalu Anda mendapat perintah berbaris dari majikan yang bekerja dengan klien atau sendiri dalam bisnis perangkat lunak, sekarang semua tanggung jawab yang pernah didistribusikan antara pengujian ahli, manajemen program, dll, adalah milik Anda. Dan sekarang Anda bekerja dengan klien yang tidak berkecimpung dalam bisnis perangkat lunak; mereka berada di bisnis lain yang membutuhkan perangkat lunak, dan mereka tidak memiliki visi yang jelas dan tepat tentang apa yang mereka inginkan dari Anda. Ini adalah tantangan yang jauh lebih besar daripada yang terlihat.

*Catatan:* Di sini, saya menggambarkan klien yang lebih kecil yang menginginkan pasukan satu orang dari pengembang mereka. Ini bukan satu-satunya rute yang dapat diambil oleh seorang freelancer, dan itu bukan satu-satunya klien yang bekerja dengan kami di Toptal, tetapi ini adalah rute yang paling saya nikmati. Tentu saja, jika Anda bekerja dalam tim dan tidak bekerja sendiri, beberapa hal di bawah ini tidak akan berlaku. Misalnya, jika Anda menggunakan metodologi Agile atau Scrum, Anda mungkin ingin menyusun pencapaian Anda sedikit berbeda.

Anda semua pernah mendengar tentang pentingnya komunikasi. Anda tidak dapat bekerja dengan mendapatkan beberapa kalimat deskripsi singkat melalui Skype dan mengatakan "Sampai jumpa dalam tiga bulan setelah saya selesai." Anda harus berkomunikasi dengan klien Anda dan pada setiap tahap pekerjaan Anda pastikan bahwa Anda memiliki gagasan yang sesuai tentang tujuan tersebut, karena memang jarang klien akan mengirimi Anda gambar rangka dan spesifikasi fungsional yang terperinci. Anda akan mendapatkan gambaran yang sangat umum tentang apa yang seharusnya dilakukan, terlihat, dan mengalir dari perangkat lunak tersebut. Jika Anda menulis aplikasi berdasarkan deskripsi sepintas yang biasanya Anda mulai, hampir tidak ada kemungkinan klien Anda akan senang dengan hasilnya. Pada setiap tahap, Anda harus mengulangi cara Anda mendekati kesepakatan.

Setelah bekerja selama bertahun-tahun di perusahaan yang bergerak dalam bisnis perangkat lunak, di mana semua orang dalam tim berasal dari budaya yang sama, berbicara bahasa asli yang sama, bekerja di lorong yang sama, bertemu satu sama lain setiap hari, dll., patut dicatat bahwa perusahaan masih tidak mendapatkan apa yang diinginkan separuh waktu. Jangan salah: tantangan di sini sangat besar.

Mengapa Dokumen Desain Perangkat Lunak Penting

Jadi, ketika Anda mengambil proyek baru, bahkan sebelum Anda membuka Xcode atau Visual Studio, Anda harus memiliki tujuan desain yang jelas dan disepakati . Dan tujuan ini harus ditetapkan dalam dokumen spesifikasi. Jika klien belum menulisnya, Anda harus menulisnya, dan mengirimkannya kepada mereka untuk ditinjau bahkan sebelum Anda membuka IDE Anda. Dan jika Anda menemukan klien yang mengatakan, "Kami tidak punya waktu untuk dokumen desain", terus terang, Anda harus meninggalkan proyek karena Anda memiliki masalah di depan. Spesifikasi tidak perlu terlalu panjang; itu bisa hanya beberapa halaman, tetapi setidaknya itu harus menata antarmuka pengguna, menyertakan gambar rangka (jika ada komponen UI), dan menetapkan tonggak penyelesaian.

Tanpa dokumen ini, Anda akan berakhir dalam lingkaran dalih yang sengit, klien memperdebatkan apa yang mereka katakan kepada Anda atau apa yang Anda katakan kepada mereka, dengan marah mengirimkan potongan-potongan komunikasi sebelumnya, menafsirkan dan berdebat sampai saatnya tiba ketika klien menuntut bahwa Anda membuat perubahan untuk membuat aplikasi sesuai dengan "apa yang sebenarnya mereka minta", dan mengharapkan Anda untuk membuat perubahan itu tanpa bayaran.

Dengan dokumen desain perangkat lunak ini, Anda akan memiliki jawaban untuk setiap pertengkaran seperti itu: ketika ketidaksepakatan muncul, Anda dapat merujuk ke spesifikasi yang disetujui dan ditandatangani klien, dengan menunjukkan bahwa Anda telah memenuhinya dengan surat itu. Alih-alih argumen marah, Anda akan membuat amandemen dan klarifikasi dokumen. Jika ada, klien akan meminta maaf karena membiarkan ketidaktepatan lolos sejak awal.

Kita semua menginginkan klien yang puas. Kita semua menginginkan hubungan kerja yang bersahabat. Dan kita semua menginginkan kebanggaan atas pekerjaan yang dilakukan dengan baik. Tetapi ini tidak dapat dicapai jika ada ketidakjelasan apa pun tentang apa sebenarnya pekerjaan itu . Jika klien Anda mengatakan bahwa dokumen desain terlalu banyak pekerjaan ekstra, itu tugas Anda untuk menjelaskan kepada mereka bahwa pekerjaan ekstra yang sebenarnya akan muncul ketika revisi perlu dilakukan karena semacam kesalahpahaman. Jika klien masih bersikeras bahwa Anda maju tanpa dokumen seperti itu, Anda harus menerima kenyataan bahwa Anda memiliki hubungan yang tidak dapat dijalankan dan pergi.

Apa yang Sebenarnya Harus Ditentukan oleh Spesifikasi Desain Perangkat Lunak?

Paling tidak, itu harus berupa deskripsi aplikasi yang diinginkan, kriteria penyelesaian, dan pencapaian. Ingat, Anda membagikan apa yang paling tepat digambarkan sebagai persyaratan dan dokumen fungsi, bukan spesifikasi implementasi. Dan kecuali implementasi spesifik adalah tujuan klien yang dinyatakan, bagaimana Anda membuatnya bekerja terserah Anda.

Antarmuka pengguna

Sebagian besar proyek adalah aplikasi, bukan perpustakaan atau kerangka kerja. Tetapi jika Anda memiliki salah satu dari ini sebagai kiriman, anggap diri Anda beruntung karena antarmuka pengguna jauh dan merupakan komponen paling bermasalah dari templat dokumen desain Anda , dan hampir selalu mengarah pada kesalahpahaman. Banyak klien akan mengirimi Anda ilustrasi sempurna yang dibuat dalam editor grafis oleh seorang desainer grafis yang bukan seorang programmer. Tapi masalahnya adalah: ilustrasi ini tidak mengatakan apa-apa tentang animasi, status kontrol (misalnya, Apakah tombol ini dinonaktifkan? Apakah itu hilang saat tidak dapat digunakan?), atau bahkan tindakan apa yang harus dilakukan saat tombol ditekan.

Sebelum Anda mulai menulis kode di balik ilustrasi ini, Anda harus bisa menjawab semua pertanyaan itu. Secara khusus, Anda harus tahu:

1. Apakah kontrol selalu terlihat dan/atau diaktifkan? Dalam kondisi apa keadaan mereka berubah?
2. Terlihat seperti bitmap—apakah itu sebuah tombol?
3. Transisi apa yang terjadi antara status dan tampilan ini? Dan bagaimana mereka harus dianimasikan?

Jika terserah Anda untuk membuat UI untuk persetujuan klien, lakukan hal yang sama secara terbalik: gunakan alat gambar rangka dan buat satu set lengkap tata letak layar, termasuk varian apa pun yang ditampilkan tampilan dalam status aplikasi yang berbeda. Ini bisa menjadi pekerjaan yang melelahkan dan melelahkan, tetapi Anda tidak akan menyesalinya—ini dapat menyelamatkan Anda dari penulisan ulang kode dalam jumlah besar dan pembuatan ulang antarmuka karena kesalahpahaman kecil dengan implikasi besar. Jika Anda membuat aplikasi ganda (misalnya, untuk iPhone dan iPad), buat gambar rangka terpisah untuk keduanya.

Dimensi layar juga penting. Ada (saat penulisan) tiga ukuran layar iPhone. Gambar rangka terpisah untuk layar 3,5” dan 4” mungkin berlebihan, tetapi Anda mungkin harus membuatnya; dalam kebanyakan kasus, Anda dapat dengan mudah mengubah proporsi.

Jika klien Anda memasok Anda dengan grafik, pastikan ukurannya benar dengan rasio aspek yang tepat; mengubah bitmap apa pun yang memiliki teks atau objek (seperti lingkaran) akan menimbulkan distorsi. Jika tidak cocok, beri tahu klien untuk membuatnya kembali dengan ukuran yang cocok. Jangan berasumsi bahwa Anda dapat meregangkan layar splash 3,5” menjadi splash 4” dan hanya menggelindingkannya.

Kegunaan

Pertanyaan kunci untuk ditanyakan dalam dokumen desain aplikasi:

• Apa yang dilakukan aplikasi tersebut, dan seberapa cepat ia melakukannya?
• Apa saja kondisi kegagalan yang mungkin terjadi dan bagaimana penanganannya?
• Operasi satu kali apa yang dilakukan pada eksekusi pertama (yaitu, setelah instalasi)?
• Jika pengguna membuat entri dalam bentuk apa pun (misalnya, bookmark), apa batasannya?

Umumkan ide-ide ini, dan sedetail dan selengkap mungkin—karena kesalahan atau kesalahpahaman di sini berarti menulis ulang kode.

Tonggak sejarah

Template spesifikasi Anda harus mengatur tonggak pencapaian yang jelas. Jika klien Anda menulis desain antarmuka fungsional dan pengguna, Anda selanjutnya harus menyetujui serangkaian pencapaian. Terkadang ini juga merupakan ambang penagihan, tetapi setidaknya mereka memberikan metrik yang jelas menuju penyelesaian. Tonggak sejarah mungkin dalam hal fungsionalitas dan/atau komponen; mereka bahkan mungkin aplikasi terpisah jika pertunjukan melibatkan serangkaian kiriman. Jika memungkinkan, tonggak sejarah harus memiliki durasi yang kira-kira sama.

Contoh Spesifikasi Desain Perangkat Lunak

Di sini, saya akan menyusun contoh struktur dokumen desain yang tepat. Tentu saja template ini harus disesuaikan dengan kebutuhan. Untuk contoh lain, lihat spesifikasi sampel Joel Spolsky, berdasarkan artikel ini. Dia mendekati dokumen itu sedikit berbeda, tetapi berbagi sentimen yang sama.

Pernyataan Tujuan

Sertakan paragraf pendek yang menjelaskan proyek dan audiens yang dituju.

Deskripsi Fungsional

Apa yang dilakukan aplikasi? Status aplikasi apa (deskripsi tingkat tinggi dari skenario pengguna inti) yang akan ditemui pengguna?

Misalnya, deskripsi fungsional Anda mungkin terlihat seperti:

• Lari pertama
• Membuat _____ Baru (permainan, penelusuran, dll.)
• Operasi
• Latar Belakang dan Perilaku Latar Depan

Antarmuka pengguna

Sertakan gambar rangka untuk setiap halaman, dengan deskripsi mendetail tentang:

• Setiap kontrol, termasuk status (diaktifkan/dinonaktifkan/disorot) dan operasi.
• Orientasi dan transisi yang didukung di antara mereka.
• Fungsionalitas diwakili.
• Penanganan kesalahan.
• Dimensi dan batasan.

Berikut adalah gambar rangka yang terkait dengan aplikasi iOS terbaru saya, NotifEye:

Jika Anda tertarik, saya membuat maket ini menggunakan alat wireframing Balsamiq.

Misalnya, deskripsi UI Anda mungkin terlihat seperti:

• Bilah Navigasi
  • Kontrol navigasi kiri: kembali ke halaman beranda
  • Bilah judul: layar saat ini atau nama operasi
  • Tombol baru: buat Hal baru
• Tampilan Tabel
  • Bagian 0: Judul bagian
  • Bagian 0 baris:
    • Kontrol baris 0 (misalnya, gambar)
    • Baris Teks 0
    • Baris Teks 2

Tonggak sejarah

Seperti dijelaskan di atas, tenggat waktu untuk penyelesaian dan hasil yang diharapkan.

Misalnya, bagian pencapaian di templat dokumen desain Anda mungkin terlihat seperti:

1. Aplikasi Fasad menampilkan layar dan dengan transisi sementara dan contoh gambar/teks
2. Protokol Komunikasi: aplikasi terhubung ke jaringan/server
3. Tonggak Fungsional 1: …
4. Aplikasi Alpha (dengan fungsionalitas penuh)
5. Stabilitas
6. Melepaskan

Memastikan Dokumentasi Perangkat Lunak Tetap Relevan

Saya tidak bermaksud menyiratkan bahwa fase desain selesai setelah Anda dan klien Anda menyetujui dokumen spesifikasi. Akan selalu ada detail yang tidak pernah Anda pertimbangkan, dan Anda dan klien akan, saat melihat hasil antara, menemukan ide-ide baru, perubahan desain, kekurangan desain yang tidak terduga, dan saran yang tidak dapat dijalankan.

Desainnya akan berkembang, dan perubahannya harus terekam dalam dokumen Anda. Dalam 25 tahun pengalaman saya, saya tidak pernah sekalipun mengerjakan proyek di mana hal ini tidak terjadi—dan itu termasuk aplikasi saya sendiri (yaitu, di mana saya adalah klien saya sendiri). Bahkan kemudian, saya membuat dokumen desain dengan spesifikasi rinci, dan menyesuaikannya seperlunya.

Di atas segalanya, tetap berhubungan. Setidaknya beberapa kali seminggu, hubungi klien Anda, laporkan kemajuan Anda, minta klarifikasi, dan pastikan Anda memiliki visi yang sama. Sebagai tes lakmus untuk komunikasi Anda, cobalah dan pastikan bahwa Anda dan klien Anda memberikan jawaban yang sama untuk tiga pertanyaan ini:

1. Apa yang baru saja dikerjakan pengembang?
2. Apa yang sedang dikerjakan pengembang saat ini?
3. Apa yang akan dikerjakan pengembang selanjutnya?