Studi lapangan tentang konsep "Dokumentasi sebagai kode"

Halo semuanya! Nama saya Denis Oleynik, saya bekerja sebagai direktur teknis di 1Service.

Di perusahaan kami, kami menyediakan banyak waktu untuk bekerja dengan persyaratan. Ketika kami memperoleh pengalaman, kami mulai menyadari bahwa alat yang biasa digunakan dalam mengembangkan produk perangkat lunak membawa kami ke keadaan di mana kami tidak dapat mengatakan bahwa kami menyadari persis apa yang diinginkan pelanggan dari kami. Tepatnya karena pada beberapa titik ada kesenjangan persyaratan yang dikumpulkan pada awalnya dari implementasi perangkat lunak mereka dan pengujian selanjutnya.

Baris ini berada di antara persyaratan yang dicatat dalam Confluence dan tugas untuk implementasinya di Jira. Garis lain antara kasus uji dalam alat pengujian dan persyaratan yang sama dalam Confluence, dengan memperhatikan kode yang terkait dengan tugas-tugas di Jira. Kurangnya jawaban yang jelas untuk pertanyaan: "mengapa / mengapa kita melakukannya dengan cara ini" atau "apakah kita melakukan segala sesuatu yang diinginkan pelanggan dari kita" - membuat kami sangat prihatin.

Dan pada titik tertentu, tampaknya bagi kita bahwa konsep "dokumentasi adalah kode" (dokumentasi sebagai kode) akan memungkinkan kita menemukan jawaban atas pertanyaan-pertanyaan ini. Konsep "dokumentasi adalah kode" mengasumsikan bahwa kami menyimpan persyaratan, solusi arsitektur, instruksi pengguna dalam bentuk file teks sederhana yang dapat diversi dengan menggunakan sistem kelas (D) VCS , idealnya model input-output data juga harus disimpan dalam flat bentuk teks. Dokumen “dapat dibaca” nyata (serta modul yang dapat dieksekusi) akan muncul sebagai hasil dari perakitan proyek. Dalam hal ini, dokumentasi teknis akan berkembang seiring dengan pengembangan seluruh proyek pada prinsip-prinsip yang sama dari versi kode, yang akan memungkinkannya untuk memenuhi kriteria penelusuran, verifikasi, dan relevansi ujung-ke-ujung. Juga, pendekatan ini secara native memecahkan masalah pengorganisasian yang disebut "versi dasar persyaratan" (baseline), yang bagi banyak sistem manajemen persyaratan menjadi masalah nyata. Secara khusus, dalam Confluence disarankan untuk menyelesaikan masalah ini dengan membuat salinan ruang asli di mana persyaratan dibuat, sementara koneksi dan faktor keturunan dari persyaratan terputus. Sebenarnya, artikel ini dikhususkan untuk penelitian lapangan konsep ini di perusahaan kami.

Latar belakang

Apa, menurut pendapat kami, menghentikan penggunaan luas konsep ini di antara massa adalah kesengsaraan alat untuk representasi visual dan pengelolaan persyaratan dalam bentuk teks datar. Ini berarti bahwa Anda tidak akan menampilkan file teks datar Pemilik Produk sehingga dia melihat Lingkup Proyek di dalamnya, Anda tidak dapat menampilkan file teks pada halaman presentasi untuk para pemangku kepentingan, mereka tidak memiliki grafik, grafik dan gambar pada tahap pengeditan - dan ini sudah membuat para analis bisnis jijik yang pada dasarnya harus menghasilkan konten. Dan hanya pengembang yang senang dan berteriak: "keren! hanya hardcore! lebih banyak komitmen! ”dan bidat lainnya.

Ada hal lain yang agak halus. Untuk beberapa alasan, pembela untuk konsep "dokumentasi adalah kode" yakin bahwa segera setelah dokumentasi berada di sebelah kode dalam repositori, ini akan mengarah pada adaptasi wajib dan sinkronisasi dengan perubahan dalam kode, yang akan membuatnya tetap up to date ( Bagian 1.2.1) ) Namun menurut kami, saat ini akan tetap menjadi masalah disiplin, karena tidak ada yang mengganggu untuk mengubah kode, dan dokumentasi tidak berubah. Artinya, relevansi dokumentasi dengan implementasi konsep tersebut diserahkan kepada manajemen proses pengembangan, di mana langkah wajib sebelum rilis adalah untuk "memeriksa relevansi dokumentasi." Dalam hal ini, "dokumentasi adalah kode" tidak jauh dari file Word, jika Anda tidak mempertimbangkan beberapa otomatisasi dalam hal kompilasi dokumen yang dihasilkan.

Ya, ya - pertama, “tidak nyaman, dicintai, kering,” dan kedua, chip teknis “menutupi dengan kain” masalah memperbarui dokumentasi. Ada stereotip yang umum: "kita oleh ajail - tetapi kita tidak memerlukan dokumentasi di ajail!" Singkatnya, ini tidak sepenuhnya benar. Saya suka membantah kesalahan ini dengan membandingkan pendekatan Use Case dan User Story dari buku Karl Wigers yang sangat bagus, “Pengembangan Kebutuhan Perangkat Lunak” [4]. Jika kami mengaitkan pendekatan pengembangan berdasarkan pada User Stories dengan metodologi Agile, maka Wigers merumuskan evolusi persyaratan berdasarkan pada User Stories dengan cara ini:

Riwayat pengguna → (diskusi) → Riwayat pengguna yang diperbarui (dengan kriteria penerimaan) → (diskusi) → Tes penerimaan

(hlm. 169, Gbr. 8-1). Dengan demikian, dokumentasi keluaran sebagai hasil dari evolusi persyaratan awal dalam proyek pengembangan tangkas adalah tes penerimaan. Saat ini, teknik yang cukup umum untuk mengatur pengujian penerimaan adalah dengan menggunakan skrip uji yang ditulis dalam bahasa Gherkin [5], disimpan dalam apa yang disebut file fitur (sederhana, teks).

Oleh karena itu, untuk mendukung implementasi konsep "dokumentasi adalah kode" dalam proyek tangkas, kita membutuhkan alat yang akan menyertai evolusi persyaratan dari format Kisah Pengguna ke tes penerimaan , yang, sebagai hasil dari eksekusi yang sukses, akan menghasilkan dokumentasi terbaru. Sayangnya, sampai saat ini, alat yang sepenuhnya mendukung proses ini (atau setidaknya mendalilkan keinginannya untuk mendukungnya) tidak ada.

Arsitektur alat penelitian

Jadi, tidak ada alat, tapi saya ingin menjelajahi konsepnya. Dari keputusasaan, kami harus mengembangkannya. Jika alat seperti itu (sebut saja StoryMapper) sudah ada, jenis arsitektur apa yang harus dimilikinya untuk mengintegrasikan secara tidak mencolok, dengan tekanan minimal, ke dalam ekosistem yang ada dalam proses pembangunan? Jika ini sudah merupakan proses pengembangan built-up, maka loop CI / CD mungkin sudah berjalan di dalamnya, dan sistem kontrol versi, kemungkinan besar berbasis git, pasti akan digunakan. Dalam hal ini, diagram di bawah ini menunjukkan tempat StoryMapper selama proses pengembangan:


Fig. 1 Tempat alat StoryMapper dalam struktur proses pengembangan

Dengan demikian, StoryMapper akan langsung berinteraksi dengan layanan hosting repositori git dan dengan loop CI / CD . Integrasi dengan layanan git hosting diperlukan untuk mendapatkan koleksi file fitur saat ini (jika ada), serta untuk menempatkan hasil perubahan pada file fitur, file layanan terkait dengan penataan dokumentasi, contoh input dan data output kembali ke repositori, dll. dll. Interaksi dengan CI kontur / CD diperlukan untuk dapat menjalankan pengujian skenario perakitan (manual atau terjadwal), dan hasil tes berikutnya - untuk mencocokkan mereka dengan sesuai fitur-file (seperti Obra th akan memverifikasi dan memeriksa relevansi dokumentasi).

Anda harus memahami bahwa StoryMapper tidak harus mengklaim judul "editor Gherkin yang lain". Ya, kemampuan dasar untuk mengedit file fitur harus diletakkan, tetapi kami jelas menyadari bahwa jika BA atau QA memilih VSC, Sublime, Notepad ++, atau bahkan vi (mengapa tidak?), Kemudian yakinkan mereka untuk bekerja dengan persyaratan hanya di StoryMapper tugasnya tidak berterima kasih, tapi agak salah. Karena itu, kami berasumsi bahwa kemungkinan beragam penggunaan StoryMapper harus diletakkan, khususnya: pengembangan fitur dalam editor favorit Anda, dan StoryMapper digunakan untuk menyusun file fitur yang sudah jadi. Lebih lanjut tentang ini di bagian tentang arah penelitian.

Fungsi Minimum yang Dibutuhkan

Karena StoryMapper saat ini dalam status MVP, ini adalah persyaratan yang sangat minimum yang kami buat untuk itu sehingga benar-benar dapat mulai digunakan:

• Pemetaan cerita berbasis Git;
• Gherkin-editor;
• Meluncurkan perakitan pengujian skenario (secara manual dan sesuai jadwal);
• Refleksi hasil pengujian skenario pada peta cerita pengguna.

Saya tidak akan memikirkan fungsi alat ini, karena topik artikel ini adalah jalannya operasi, dan bukan pisau bedah dokter bedah.

Area Penelitian

Gagasan utamanya adalah ini: jika, dengan menggunakan konsep "dokumentasi adalah kode," Anda tidak pergi dari persyaratan pelanggan dan menulis semacam dokumentasi sewenang-wenang saat Anda menulis kode, maka dokumentasi tersebut akan mati dan menjadi tidak relevan secepat versi dengan file dalam format MS Kata Oleh karena itu, kami ingin memikirkan dan mengeksplorasi opsi penggunaan konsep dalam kaitannya dengan siklus pengembangan penuh. Di sisi lain, kami juga tertarik pada momen transisi ketika tim tidak menggunakan konsep "dokumentasi adalah kode", tetapi ada keinginan untuk menerapkannya - bagaimana bertindak dalam kasus ini?

Jadi, StoryMapper adalah alat, itu tidak mengatur satu-satunya kasus penggunaan yang benar. Sebaliknya, setiap pengguna potensial dapat melihat opsi mereka untuk menggunakan alat ini. Kami fokus pada tiga bidang utama:

• Pengembangan yang fleksibel: dari peta cerita hingga tes penerimaan;
• Menyusun dan memvisualisasikan kumpulan file fitur;
• Pemantauan produktivitas.

Di bawah ini saya akan menjelaskan secara rinci hasil apa yang telah kami capai di setiap arah.

Pengembangan fleksibel: dari kartu cerita hingga tes penerimaan

Arah ini melibatkan pengembangan produk baru atau penyempurnaan produk yang sudah ada. Pekerjaan ke arah ini terjadi di bawah nama kode "BDDSM": sebagai kombinasi dari teknik Pemetaan Cerita dan metodologi pengembangan BDD . Dan itu berakar.

Jadi, sebagai permulaan, repositori git dibuat untuk file fitur, cabang dialokasikan di dalamnya untuk berinteraksi dengan StoryMapper. Sebuah proyek dibuat di StoryMapper, terhubung ke analis bisnis yang akan mengerjakan proyek. Berkomunikasi dengan para pemangku kepentingan, analis bisnis mulai merumuskan visi bersama dari produk dan memperbaikinya dalam bentuk kerangka peta cerita pengguna [1,2], pertama sketsa tingkat pertama UF :


Fig. 6 Kerangka tingkat atas dari peta cerita pengguna (dapat diklik)

Dan kemudian secara bertahap mengisi aktivitas pengguna tingkat kedua:

Fig. 7 Kerangka tingkat kedua dari peta cerita pengguna

Karena setiap kartu adalah file teks, baik pada tahap pengumpulan persyaratan (jika kartu dikompilasi dalam proses komunikasi dengan pengguna), atau pada tahap pasca-wawancara, hasil komunikasi ditransfer langsung ke kartu UF dan UA . Ini adalah dasar untuk dekomposisi lebih lanjut dari persyaratan ke tingkat cerita pengguna.


Fig. 8 Teks persyaratan bebas sintaks Gherkin di level UF

Selanjutnya, analis bisnis menyadari bagaimana menguraikan aktivitas pengguna menjadi cerita pengguna, dan membentuk tingkat peta ketiga di StoryMapper - AS . Isolasi AS dikaitkan dengan perumusan kriteria penerimaan, yaitu, jika "Anda sebagai seseorang menginginkan sesuatu," maka kami akan memeriksa setelah fakta bahwa Anda menerimanya [3]. Kriteria penerimaan sebagai permulaan juga dapat ditetapkan di AS sebagai teks tetap.

Setelah kriteria penerimaan ditetapkan dan disepakati dengan para pemangku kepentingan, analis bisnis menempatkannya dalam bentuk skrip dalam bahasa Gherkin. Bahkan, teks "Skenario: KP-No" ditambahkan ke setiap kriteria penerimaan, yang mengubah kisah pengguna abstrak sampai sekarang menjadi file fitur.


Fig. 8.1 Kriteria penerimaan untuk cerita pengguna sebagai skrip di Gherkin

Setelah itu, setiap skenario diuraikan dengan beberapa langkah yang diperbesar yang mengungkapkan bagaimana tepatnya kriteria penerimaan tertentu akan diperiksa. Selanjutnya, langkah-langkah ini diprogram oleh pengembang atau diketik dari perpustakaan langkah-langkah kerangka kerja Gherkin yang digunakan dan diekspor ke skrip ekspor.

Sejalan dengan ini, bangku tes diatur di mana server perakitan akan menjalankan tes fungsional dan menunggu saat ketika AS dengan skrip siap. Karena produk dan skenario yang menerapkan kriteria penerimaan siap, server perakitan mulai mengeluarkan laporan dalam format Allure dan Mentimun dan mengirimkannya ke StoryMapper, yang pada gilirannya memproyeksikan hasil perakitan dalam format Mentimun ke peta cerita pengguna:


Fig. 9 Peta cerita pengguna dengan hasil skrip

Pada saat yang sama, StoryMapper memberikan tiga tingkat pemahaman tentang kesiapan produk: UF adalah tingkat teratas yang menunjukkan jumlah skrip yang berfungsi dengan benar (memenuhi kriteria penerimaan), bekerja dengan kesalahan, dan belum siap. Faktanya, level atas adalah indikator kesiapan produk dan indikator berapa banyak lagi yang harus dilakukan (ini adalah level pemilik produk). Level yang lebih rendah memungkinkan Anda untuk mengetahui dengan tepat aktivitas pengguna seperti apa yang ada kesulitannya, dan di mana Anda perlu melakukan upaya untuk menyelesaikan produk (ini adalah tingkat master scrum ke tingkat yang lebih besar dan pemilik produk pada tingkat lebih rendah). Level AS yang lebih rendah adalah level di mana analis bisnis, pengembang, dan QA berinteraksi, bersama-sama mengembangkan produk yang diharapkan oleh para pemangku kepentingan dari mereka.

Juga, di salah satu langkah terakhir dari jalur perakitan, dokumentasi otomatis dibuat. Anda dapat membaca lebih lanjut tentang ini dengan rekan kerja . Ini bukan satu-satunya pilihan, kami berencana untuk memasukkan paket Acar dalam alat kami - standar de facto di dunia "dokumentasi langsung".

Menyusun dan memvisualisasikan kumpulan file fitur

Bekerja ke arah ini, kami mempertimbangkan kasus seperti itu. Tim pengembangan, di tengah hype sekitar topik BDD, pengujian fungsional dan standar pengembangan industri, berupaya untuk menulis file fitur. Dan menerobos duri, telah mengumpulkan koleksi yang cukup besar di repositori. Namun, ketika Anda memiliki 10 file dalam koleksi Anda, laporan dalam format Allure masih memberikan beberapa gambaran yang dapat diandalkan tentang keadaan produk. Tetapi jika jumlah file fitur diukur dalam lusinan, dan kadang-kadang ratusan, maka cepat atau lambat Anda akan ingin membuat mereka entah bagaimana. Hal pertama yang terlintas dalam pikiran adalah mengurutkannya ke dalam folder tematik. Dan untuk apa? Oleh para pemangku kepentingan, oleh metadata, oleh subsistem? Ini jauh dari pertanyaan kosong. Dan jika nanti ternyata fitur-file itu pada awalnya ditulis sebagaimana Tuhan akan memasukkannya ke dalam jiwa, dan ada skrip yang terkait dengan beberapa folder sekaligus, lalu bagaimana?

Jadi, use case ini menyiratkan keinginan untuk membersihkan dokumentasi Anda untuk beralih dari "fitur secara terpisah, dokumentasi secara terpisah" ke "dokumentasi adalah kode". Ketika repositori seperti itu terhubung ke StoryMapper, maka semua file fitur jatuh ke kolom pertama di bawah UF0 dan UA0. Langkah selanjutnya dalam penataan adalah menyusun kerangka struktur. Di StoryMapper, semuanya adalah UF dan UA yang sama , tetapi tidak ada yang bersikeras untuk mempertimbangkannya hanya dari sudut ini. Mereka dapat dianggap hanya sebagai 2 tingkat hierarki, di mana dimungkinkan untuk menempatkan file fitur yang sebelumnya tidak terstruktur. Setelah struktur diatur, file fitur dari kolom pertama ditarik terpisah di bawah UA yang sesuai. Tidak diragukan lagi, proses ini menyebabkan serangan refleksi dan refactoring fitur, karena ketika Anda menyeret, seluruh kedalaman kekacauan yang terjadi selama penulisan awal mereka menjadi jelas. Terkadang cukup untuk mentransfer skrip dari satu file ke file lain, kadang-kadang membagi satu file besar menjadi beberapa untuk memulihkan konektivitas semantik, dan kadang-kadang hanya membuangnya ke tempat sampah, karena naskah kuno yang tidak dapat dieksekusi terbaring di repositori.

Jika jalur perakitan telah dikonfigurasikan (well, karena ada repositori file fitur, maka mereka harus dikumpulkan di suatu tempat), maka Anda perlu menambahkan langkah di dalamnya untuk mengirim hasil perakitan ke StoryMapper. Hasil akhir akan menjadi gambar terakhir dari bagian sebelumnya (Gbr. 9): file fitur terstruktur dengan tanda pada hasil skrip mereka.

Bagaimana cara menggunakan gambar seperti itu? Dapat ditunjukkan kepada tim manajemen untuk melaporkan hasil tim dan menunjukkan tingkat kesiapan / kualitas produk. Ini dapat digunakan oleh tim dalam melakukan retrospektif untuk memperbaiki DoD atau untuk memperbaiki proses. Ini dapat digunakan untuk perawatan backlog, tetapi ini sudah membutuhkan pekerjaan sesuai dengan skenario yang dijelaskan di bagian sebelumnya, ketika setelah penataan awal persyaratan, pengembangan lebih lanjut akan dilakukan dalam siklus penuh melalui (atau setidaknya memperhitungkan) StoryMapper.

Pemantauan Produk

Kasus penggunaan sisi lain yang telah berakar dalam praktik kami. Bahkan, ini adalah topik modern dan modis - untuk menguji langsung dalam produk mengapa tidak. Lagi pula, tidak ada kesalahan, tidak, dan ya mereka akan membuat jalan mereka. Ini menjadi sangat relevan jika aktivitas TI bukan profil untuk perusahaan dan pengembangannya adalah outsourcing, khususnya, ini adalah toko online kecil dan menengah.

Seperti yang kita lihat. Pilihan sederhana: dari serangkaian tes fungsional, subset tertentu dari tes database non-modifikasi dipilih yang memeriksa front-end.Opsi kedua: skenario yang menguji logika bisnis disorot, sementara sesi di mana tes dimulai diluncurkan dalam mode uji khusus, di mana modifikasi data tidak tercermin pada database, tidak merusak statistik dan tidak berpartisipasi dalam pertukaran dengan sistem akuntansi. Ketika kumpulan skrip ini telah dikompilasi, skrip ini terikat dengan jadwal dan, dengan frekuensi yang diberikan, dieksekusi langsung pada produk. Hasil dari eksekusi juga tercermin dalam StoryMapper dan Allure, tetapi yang lebih penting, jika ada kesalahan dalam test suite ini, orang-orang yang tertarik pada bisnis akan menerima pemberitahuan melalui email, dan dengan demikian, mereka akan dapat menavigasi secara online bagaimana rilis selanjutnya dari pemasoknya. Layanan TI merusak alat bisnis intinya.

Jika langkah-langkah skrip termasuk memeriksa durasi eksekusi, dan jika terjadi pelanggaran waktu kontrol, hentikan eksekusi skrip dengan kesalahan, maka skrip ini akan mencerminkan persyaratan kinerja yang tidak fungsional. Karenanya, jika perubahan kode, peningkatan beban, penurunan kinerja hosting telah memengaruhi kecepatan produk, maka seseorang yang tertarik secara finansial dalam kapasitas kerja akan diberitahu tentang hal ini.

Jadi, untuk mengatur pemantauan produk, Anda perlu menyiapkan:

• repositori dengan sekumpulan skrip yang disesuaikan untuk produk;
• jalur perakitan yang menyediakan skrip dalam produk, dengan kait yang dikonfigurasi untuk dijalankan;
• StoryMapper dengan repositori yang terhubung dan hook yang dikonfigurasi untuk menerima hasil tes;
• StoryMapper mengonfigurasi jadwal startup dan pemberitahuan kesalahan.

Arah pengembangan

Sekali lagi, StoryMapper saat ini dalam keadaan MVP. Namun demikian, ia mengizinkan melakukan "eksperimen pada orang", yang, menurut saya, diselesaikan lebih dari sukses. Ya, di pintu keluar, tentu saja, muncul “nafsu makan” yang sama. Berikut adalah daftar yang tidak lengkap tentang apa yang ingin saya tambahkan ke alat:

• tampilan di alat dokumentasi yang sangat "hidup" yang harus menjadi hasil akhir dalam konsep "dokumentasi adalah kode";
• diskusi skenario antara peserta proyek (komentar, kolaborasi dll);
• ekspor / impor kartu cerita khusus ke / dari Excel;
• semacam integrasi dengan Jira (tetapi ada lebih banyak pertanyaan daripada jawaban).

Saya melihat risiko sedemikian rupa sehingga alat penggunaan internal dapat mulai mendominasi metodologi dan konsep, dan kami akan terlibat dalam disiplin diri dan refleksi daripada menghasilkan ide-ide menarik dan meningkatkan proses pengembangan. Oleh karena itu, dalam waktu dekat kami memiliki rencana untuk memberikan akses ke alat dalam edisi terbatas untuk terinspirasi oleh umpan balik dan untuk merevisi arah pengembangan.

Bagaimana saya bisa mencoba

Saya tidak secara langsung mengharapkan ketertarikan yang meledak-ledak pada topik yang diangkat di sini (walaupun saya akrab dengan istilah "habraeffect"), jadi jika seseorang tiba-tiba menjadi tertarik dan ingin menyentuh instrumen dengan tangan mereka, bicarakan evolusi dan verifikasi persyaratan (yang lebih menarik!) - ketuk telegram kami Anda bisa menyetujui semuanya.

Referensi dan referensi

1. Jeff Patton, Cerita Kustom. Seni pengembangan perangkat lunak tangkas, St. Petersburg, Peter, 2017.
2. Mike Cohn, Cerita Kustom. Pengembangan perangkat lunak yang fleksibel, M.-SPb.-K, Williams, 2012.
3. Gojko Adjic, Spesifikasi dengan Contoh, NY, Manning Publication, 2011.
4. Karl Wigers, Joy Beatty, Pengembangan persyaratan perangkat lunak, M.: Edisi Rusia; SPb.: BHV-Petersburg, 2014.
5. Artikel pengantar BDD Dan North “What's in a story”
6. Informasi tentang konsep "Dokumentasi adalah kode" di komunitas "Tulis dokumen"
7. Penerapan konsep "Dokumentasi - kode ini" dalam proyek " docToolchain "