Beberapa bulan yang lalu, saya menyelesaikan salah satu tahapan jalur profesional saya dengan Shiva multi-bersenjata di sebuah startup untuk mengembangkan sistem manajemen laboratorium pengujian non-destruktif. Saya akan memberi tahu Anda bagaimana saya dapat mendokumentasikan bagian dari pengembangan terkait dengan menghubungkan dan menghasilkan dokumen dalam volume yang cukup untuk penggunaan lebih lanjut diam-diam dari sistem yang dibuat selama dua tahun.
Saya akan mencoba memberikan pembaca materi yang bermanfaat sebanyak mungkin, dan pada saat yang sama mengamati kepentingan proyek dan tidak membocorkan nuansa implementasi dan penggunaan internal.
Diberikan:
- tim pengembangan keren dan tentu saja manajer proyek. Pada saat dimulainya proyek, saya bekerja sebagai art director di salah satu studio Tomsk, kemudian saya berakhir di tim startup
- memulai dengan tanggal beton bertulang untuk acara tertentu - akselerasi dimulai di FRII
- set templat awal dari 15+ dokumen dengan berbagai ukuran dari 1 halaman hingga 100+ halaman dalam satu dokumen dengan kondisi koneksi berbeda
- proyek pihak ketiga yang harus diintegrasikan dengan solusi masa depan
- perancang (analis, perancang, perancang, art director, pemilik produk, manajer produk semuanya digabung menjadi satu)
Tantangan:
- meluncurkan proyek tepat waktu
- jangan mati tim enam bulan kemudian dalam kekacauan saat menghubungkan fungsionalitas baru dan bahkan lebih banyak dokumentasi dalam sistem (jika sukses menyelesaikan percepatan)
- dengan jumlah surat minimum dan upaya yang dikeluarkan untuk mencapai dokumentasi yang sesuai
- pengalihan dokumentasi kepada tim / karyawan mana pun yang tidak berada dalam konteks
Saya harus segera mengatakan bahwa templat dokumen berikut dibuat tanpa metodologi apa pun, saya dipandu secara eksklusif oleh spesifikasi proyek, akal sehat, dan batas waktu yang mengerikan.
Analisis dan persiapan
Saya harap Anda memulai tugas non-sepele dengan menganalisis materi, dalam kasus saya materi adalah templat dokumen dan proyek yang sudah ada dengan mana integrasi diperlukan. Tetapi kemudian kita hanya berbicara tentang dokumen. Saya perlu menentukan frekuensi menggunakan jenis data yang sama di dalam dokumen yang sama dan di antara dokumen. Itu perlu untuk memahami apakah suatu sistem diperlukan saat ini atau Anda dapat dengan cepat melakukannya pada lutut terlebih dahulu, dan kemudian berurusan dengan hasilnya. Pada saat itu, diputuskan bahwa sistem itu diperlukan, karena hampir semua data, dalam satu volume atau yang lain, diulang dalam satu dokumen dan dalam seluruh paket dokumen - dan ini merupakan tanda kebingungan yang pasti sudah ada pada dokumen kedua atau ketiga saat menghubungkan.
Langkah selanjutnya adalah memahami kondisi kebersihan markup dokumen. Saya akan jelaskan. Faktanya adalah saya menerima templat dokumen yang sudah lengkap dari ahli metodologi - yang, kapan dan bagaimana dokumen-dokumen ini saya tidak tahu, bahkan jika saya tahu ini akan memberikan sedikit. Dokumen .docx di dalamnya adalah sesuatu seperti xml untuk teks dan beberapa elemen mungkin tidak terlihat secara visual dalam dokumen terbuka, tetapi hadir di markup dokumen. Bagaimana pembuat dokumen dan berbagai perangkat lunak untuk melihat dokumen akan bereaksi terhadap elemen markup ini tidak diketahui. Taruhan utama adalah pada Microsoft Word, tetapi ada OpenOffice, LibreOffice dan semuanya dapat memberikan hasil yang berbeda. Oleh karena itu, semua templat pertama kali melewati prosedur pembersihan gaya - set lengkap ulang desain apa pun dan desain ulang dengan gaya dokumen, di suatu tempat dengan menyesuaikan struktur dokumen. Dan bahkan setelah prosedur ini, kami mengumpulkan masalah dalam isi dokumen setelah generasi. Di masa depan, saya sampai pada kesimpulan bahwa jika dokumen itu kecil, lebih baik mengurutkannya dari awal, dan tidak menggunakan templat yang disediakan oleh ahli metodologi untuk bekerja, ini menghemat waktu pada dokumen hingga 5 halaman. Tak seorang pun ingin mencari alasan mengapa sesuatu berjalan, proses debugging kasus-kasus ini sangat membosankan bagi tim. Pada tahap yang sama, jika Anda memiliki paket dokumen, Anda datang ke bahasa visual yang seragam.
Dan karena kami melakukan ritual pembersihan dokumen, telur paskah dalam meta-informasi menyarankan dirinya sendiri, karena orang suka berbagi dokumen yang baik
Setelah semua pekerjaan yang berhubungan dengan persiapan dokumen, saya melanjutkan menandai dokumen untuk pembuatan otomatis.
Markup dokumen
Pada tahap ini, minta pengembang untuk format variabel yang mendukung pembuat dokumen yang dipilih oleh tim Anda sehingga Anda tidak perlu mengulanginya nanti. Saya harus mengulanginya, tetapi ini karena mengganti generator. Generator baru tidak dapat bekerja dengan variabel dalam format sebelumnya, tetapi kemampuan generator baru ternyata lebih penting bagi kami dan kami memutuskan untuk menggantinya.
Periksa kecukupan informasi dalam sistem, tentukan berapa banyak data yang tidak cukup untuk dokumen. Kapan data ini seharusnya muncul di sistem? Jika tidak ada cukup data untuk kemandirian dokumen, lebih baik menundanya. Apa itu swasembada dokumen? Dalam kasus saya, ada satu dokumen yang kami selesaikan dalam 3 tahap, tetapi langsung mencukupi untuk satu skenario tertentu, tetapi tidak mencakup sisa skenario, jadi kami memutuskan untuk menggelar dokumen untuk penjualan, meninggalkan sel kosong bagi pengguna untuk mengisi skenario yang belum ditemukan, dan kemudian menyelesaikan dokumen dengan tampilan fungsionalitas yang diperlukan.
Dokumentasi Variabel dan Antarmuka
Di awal catatan, saya menulis bahwa kami sangat terbatas pada acara tertentu. Selain itu, saya sudah merencanakan liburan. Ketika saya tidak tersedia, tetapi saya sangat perlu menambahkan variabel sistem (tidak tersedia di antarmuka pengguna akhir), para pengembang menambahkan baris dengan variabel itu sendiri, dan kemudian saya menambahkan kondisi yang hilang. Dalam hal ini, spesifikasi variabel tidak berpura-pura benar dan ideal, tetapi cukup dokumen yang berfungsi, yang kemudian diperluas dan berkembang. Tab utama dalam dokumen tidak secara struktural berubah dari awal dan pada saat kepergian saya dari proyek.
Templat "
Spesifikasi untuk bidang ini ", yang dapat Anda ambil dan gunakan dalam pekerjaan Anda. Dalam dokumen itu, saya meninggalkan sebagian data sebagai contoh. Templat ini mungkin cocok untuk dokumentasi antarmuka untuk mengontrol kualitas pengembangan. Misalnya, seorang pemilik produk tahu hasil minimum yang akan didapatnya, pengembang dengan jelas memahami apa yang diperlukan minimum untuk dibuat dari deskripsi tugas + spesifikasi bidang ini, dan jika ada sesuatu yang hilang ia akan menceritakannya, insinyur pengujian dengan jelas melihat kasus yang jelas. Pada akhirnya, semuanya berwarna hitam.
Pada awalnya, dokumen akan membutuhkan banyak waktu, tetapi kemudian akan menghemat banyak waktu yang dihabiskan, dan memperbarui kadang-kadang akan memakan waktu beberapa menit.
Konten:
- Halaman ini adalah panduan untuk seseorang di luar konteks proyek, ke mana harus mencari. Berguna untuk anggota baru dalam tim atau outsourcing proyek.
- Nama bidang
- Jenis bidang
- Bidang wajib dalam proyek (saya ingatkan Anda, kami memiliki database proyek lain) - penanda untuk menyinkronkan persyaratan pengikatan antara dokumen dan antarmuka. Jika informasi dalam dokumen ini mengikat dan sistem tidak dapat menerimanya dengan cara lain, akan perlu untuk membuat bidang ini wajib di antarmuka
- Mask bidang - format untuk merekam informasi didefinisikan dengan jelas dalam dokumentasi peraturan.
- Nilai standar
- Jumlah maksimum karakter di bidang
- Skalabilitas bidang (tergantung pada resolusi) - deskripsi perilaku elemen antarmuka tergantung pada resolusi
- Persyaratan data - interaksi apa yang diizinkan dengan elemen antarmuka, dan apa yang bisa masuk
- Sampel yang berhasil
- Placeholder - tooltip untuk pengguna di dalam elemen antarmuka
- Kustomisasi bidang - elemen antarmuka non-standar atau tugas jadi
- Informasi tambahan di sebelah bidang - ketika placeholder tidak dapat diberikan karena jumlah teks, maka kami menggunakan tooltip atau pegangan
- Jenis validasi
- Pesan validasi - kondisi dan respons sistem
- Variabel dalam templat dokumen - apa yang akan dimasukkan ke dalam templat dokumen
- Tautan ke halaman - tidak digunakan sebagai hasilnya
- Lokasi bidang di antarmuka - tidak digunakan sebagai hasilnya
Dokumentasi Sambungan Dokumen
Untuk menerima dokumen oleh pengguna akhir, itu tidak cukup untuk mengedit dan menandainya, dokumen masih perlu dihubungkan dengan benar. Ini sangat penting jika Anda memiliki template yang sama, tergantung pada kondisinya, mengubah kontennya. Untuk ini, saya menggunakan dokumen terpisah.
Templat "
Koneksi Dokumen ", saya harap bermanfaat bagi seseorang.
Konten:
- Status - menunjukkan status dokumen saat ini dalam sistem. Kami menghubungkan satu dokumen dalam 3 tahap, status dokumen itu adalah "Finalisasi"
- Dokumen - nama dokumen dalam tim, basis pengetahuan dan dalam sistem pengaturan tugas dan dokumentasi kami
- Jenis
- Format dokumen adalah ketika dokumen yang sama dapat berada dalam template yang berbeda tergantung pada peraturan dan dokumentasi teknis yang sesuai dengan dokumen ini
- Formasi - dokumen dapat berupa templat ke mana variabel hanya disubstitusikan atau dari templat 3 halaman Anda bisa mendapatkan 100+ dokumen halaman - dokumen dinamis
- Kehadiran dalam paket adalah fitur sistem, Anda bisa mendapatkan paket dokumen atau mengunduh dokumen secara terpisah
- Kondisi kehadiran - keberadaan dokumen tertentu dalam paket
- Fitur koneksi adalah bagian dari dokumen yang tidak ada dalam templat dan diatur oleh kode.
- Tautan ke file untuk terhubung
- Unduh secara terpisah
- Nama file yang akan diunduh - dokumen dalam sistem dapat disebut apa pun yang Anda suka, tetapi pengguna akhir harus melihat nama tertentu saat mengunduh
Total
Akibatnya, saya mengisi 362 baris di kedua dokumen. Volume yang mengesankan? Namun pada kenyataannya, ini adalah 30+ templat dokumen dan total 40-60 jam kerja satu orang dalam dua tahun (1-1.5 minggu) dihabiskan, tidak termasuk pengeditan templat itu sendiri dan kata-kata dari tugas koneksi.
Proyek ini berhasil melewati percepatan dalam IIDF dan datang ke bentuk tim pengembangannya sendiri. Berkat dokumentasi yang ada, anggota tim yang baru tidak perlu menyelidiki untuk waktu yang lama apa yang dilakukan sebelum mereka mengenai pembuatan dokumen. Semua anggota tim memiliki akses ke status saat ini dari dokumen yang terhubung kapan saja.
Tahapan utama dalam dokumentasi proses pembuatan dokumen:
- Analisis isi dokumen
- Kebersihan dokumen
- Perbaiki variabel secara paralel dengan markup dokumen
- Perbaiki nuansa menghubungkan templat dokumen.
Terima kasih sudah sampai di akhir.