Terkadang, tidak hanya dokumentasi itu sendiri, tetapi juga proses pengerjaan itu bisa sangat penting. Sebagai contoh, dalam kasus proyek, bagian terbesar dari pekerjaan dihubungkan dengan persiapan dokumentasi, dan proses yang tidak tepat dapat menyebabkan kesalahan dan bahkan kehilangan informasi, dan, akibatnya, kehilangan waktu dan keuntungan. Tetapi bahkan jika topik ini tidak penting bagi pekerjaan Anda dan terletak di pinggiran, proses yang benar masih dapat meningkatkan kualitas dokumen dan menghemat waktu Anda.
Pendekatan yang diuraikan di sini, dengan
contoh implementasi tertentu , memiliki ambang masuk yang rendah. Secara teknis, besok Anda bisa mulai bekerja dengan cara baru.
Pernyataan masalah
Anda perlu membuat dokumen atau kumpulan dokumen tertentu. Mungkin ini adalah dokumentasi proyek atau pencatatan jaringan Anda, atau sesuatu yang lebih sederhana, misalnya, Anda harus menggambarkan proses di perusahaan atau di departemen Anda. Secara umum, kita berbicara tentang dokumen atau kumpulan dokumen dengan teks, gambar, piring ... Kita menyulitkan tugas dengan fakta bahwa
- pekerjaan ini melibatkan kerja bersama, upaya kelompok atau beberapa kelompok karyawan
- Pada output, Anda ingin memiliki dokumen dalam format tertentu, dengan atribut gaya korporat, dibuat sesuai dengan templat tertentu. Untuk kepastian, kami akan menganggap bahwa ini adalah MS Word (.docx)
10 tahun yang lalu, pendekatannya akan jelas: kita akan membuat dokumen atau dokumen MS Word dan entah bagaimana mengatur pekerjaan pada perubahan.
Dan pendekatan ini masih valid. Itu juga digunakan oleh integrator besar ketika membuat dokumentasi proyek. Tetapi secara intuitif jelas bahwa jika Anda benar-benar intensif, dengan banyak pengeditan dan diskusi, untuk waktu yang lama mengerjakan dokumen, pendekatan ini tidak terlalu nyaman.
Contoh
Saya cukup akut merasakan masalah ini saat bekerja dalam satu integrator besar. Proses mengubah dokumentasi desain adalah sebagai berikut:
- engineer mengunduh versi terbaru dokumen MS Word (.docx)
- mengubah nama
- membuat perubahan pada mod trek
- mengirimkan dokumen dengan koreksi ke arsitek
- juga mengirimkan daftar semua koreksi dengan komentar
- arsitek menganalisis perubahan
- jika semuanya baik-baik saja, maka salin perubahan data ke file dengan versi terbaru, ubah versi, letakkan di sumber daya bersama
- jika ada komentar, maka diskusi dimulai (email atau demonstrasi)
- konsensus tercapai
- paragraf selanjutnya 3 - 9
Meskipun pekerjaan itu tidak intens, entah bagaimana, tetapi masih berhasil. Tetapi pada titik tertentu, proses ini menjadi penghambat seluruh proyek dan menyebabkan masalah. Faktanya adalah bahwa semuanya menjadi buruk segera setelah perubahan dibuat sering dan secara bersamaan oleh beberapa tim.
Jadi, ketika kami pergi ke tahap pengujian pendahuluan, masalah yang berbeda mulai muncul dan, meskipun dalam perinciannya, kami harus sering mengubah dokumentasi - empat tim yang berbeda, setiap hari, hampir bersamaan, dengan diskusi. Semua perubahan ini melewati satu insinyur - seorang arsitek. File dengan desain proyek sangat besar, dan sebagai akibatnya, arsitek kewalahan dengan pekerjaan rutin yang terkait dengan banyak penyalinan, pengeditan, membuat banyak kesalahan, saya harus memeriksa ulang, mengirim ulang, dan secara umum dekat dengan kekacauan.
Dalam hal ini, pendekatan ini, pendekatan bekerja pada dokumen MS Word, bekerja dengan mencicit besar dan menciptakan masalah.
Git penurunan harga
Menghadapi masalah yang dijelaskan dalam contoh di atas, saya mulai meneliti masalah ini.
Saya melihat bahwa menggunakan
Markdown dengan
Git saat membuat dokumen menjadi semakin populer.
Git adalah alat pengembangan. Tetapi mengapa tidak menggunakannya untuk proses dokumentasi? Dalam hal ini, masalah pekerjaan multi-pengguna menjadi terselesaikan. Tetapi untuk memanfaatkan sepenuhnya fitur Git, kita memerlukan format teks untuk dokumen, kita perlu menemukan alat lain, bukan MS Word, dan penurunan harga bagus untuk tujuan ini.
Penurunan harga adalah bahasa markup teks sederhana. Ini dirancang untuk membuat teks yang dirancang dengan indah dalam file TXT biasa. Jika kita membuat dokumen kita di Markdown, maka tautan Markdown-Git terlihat alami.
Dan semuanya akan baik-baik saja, dan di tempat ini akan mungkin untuk mengakhiri jika bukan karena kondisi kedua kami: "pada output kita memerlukan dokumen dalam format tertentu, dengan atribut gaya perusahaan dibuat sesuai dengan templat tertentu" (dan kami pertama kali sepakat bahwa untuk kepastian, itu akan menjadi MS Word). Yaitu, jika kami memutuskan untuk menggunakan Markdown, maka kami harus mengonversi file ini menjadi .docx dengan tipe yang diperlukan.
Ada program untuk mengkonversi antara format yang berbeda, misalnya,
Pandoc .
Anda dapat mengonversi file Markdown ke format .docx dengan program ini.
Tapi tetap saja, Anda perlu memahami bahwa, pertama, tidak semua yang ada di Markdown akan dikonversi ke MS Word dan, kedua, MS Word adalah seluruh negara dibandingkan dengan yang ramping, tetapi masih kota kecil, Markdown. Ada sejumlah besar semua yang ada di Word dan dalam bentuk apa pun ada di Markdown. Anda tidak bisa hanya mengambil format Penurunan harga dengan kunci Pandoc yang diinginkan ke dalam bentuk MS Word yang diinginkan. Jadi biasanya, setelah konversi, Anda harus "memperbaiki" dokumen .docx yang diterima secara manual, yang lagi-lagi dapat memakan waktu dan menyebabkan kesalahan.
Jika kami dapat menulis skrip yang secara otomatis “menyelesaikan” apa yang tidak bisa dilakukan Pandoc, itu akan menjadi solusi yang ideal.
Karena fakta bahwa fungsionalitas MS Word dan Penurunan harga tidak identik secara umum, saya pikir tidak mungkin untuk menyelesaikan masalah ini, tetapi bisakah ini dilakukan dalam kaitannya dengan situasi tertentu, persyaratan khusus? Pengalaman saya telah menunjukkan bahwa ya, itu mungkin dan kemungkinan besar itu mungkin bagi banyak orang, atau bahkan mungkin sebagian besar situasi.
Solusi dari masalah tertentu
Jadi, dalam kasus saya, setelah mengkonversi file menggunakan Pandoc, saya harus secara manual melakukan pemrosesan file tambahan, yaitu
- tambahkan bidang dalam Word dengan penomoran otomatis keterangan tabel dan gambar
- ubah style untuk tabel
Saya tidak menemukan cara melakukan ini menggunakan standar (Pandoc) atau cara yang dikenal. Oleh karena itu, saya menerapkan skrip python dengan paket
pywin32 . Akibatnya, saya mendapat otomatisasi penuh. Sekarang saya dapat mengonversi file penurunan harga ke bentuk dokumen MS Word yang diinginkan dengan satu perintah.
Lihat detailnya di
sini .
Komentar
Dalam contoh ini, saya, tentu saja, akan mengonversi beberapa file Markdown abstrak, tetapi pendekatan yang persis sama diterapkan pada dokumen "memerangi", dan pada output saya menerima hampir persis dokumen MS Word yang sama, yang sebelumnya kami terima dengan pemformatan manual.
Secara umum, dengan pywin32 kita hampir sepenuhnya mengendalikan dokumen MS Word, yang memungkinkan kita untuk mengubahnya dan membawanya ke tampilan yang diperlukan standar perusahaan Anda. Tentu saja, tujuan yang sama dapat dicapai dengan menggunakan alat lain, misalnya, makro VBA, tetapi lebih nyaman bagi saya untuk menggunakan python.
Formula singkat untuk pendekatan ini:
Markdown + Git -- () --> MS Word
Tidak begitu penting apa "sesuatu" itu. Dalam kasus saya, itu adalah Pandoc dan python dengan pywin32. Anda mungkin memiliki preferensi yang berbeda, tetapi yang penting adalah ini mungkin. Dan ini adalah pesan utama dari artikel ini.
Singkatnya, idenya adalah bahwa dengan pendekatan ini Anda hanya bekerja dengan file Penurunan harga dan menggunakan Git untuk mengatur kolaborasi dan kontrol versi, dan hanya jika perlu (misalnya, untuk memberikan dokumentasi kepada klien) secara otomatis membuat file dengan format yang diinginkan (misalnya, MS Word )
Prosesnya
Saya pikir banyak formula yang diberikan di atas sudah cukup untuk memahami bagaimana proses bekerja dengan dokumentasi dapat diatur sekarang. Namun demikian, saya biasanya fokus pada insinyur jaringan, jadi saya akan menguraikan secara umum bagaimana prosesnya sekarang terlihat dan bagaimana perbedaannya dari pendekatan mengedit file MS Word.
Untuk jelasnya, kami akan memilih GitHub sebagai platform untuk bekerja dengan Git. Kemudian Anda harus membuat repositori dan meletakkan file Markdown atau file yang Anda rencanakan untuk bekerja dengannya di cabang master.
Kami akan melihat proses berbasis aliran github sederhana.
Uraiannya dapat ditemukan di Internet dan di
Habr .
Misalkan empat orang sedang mengerjakan dokumentasi dan Anda adalah salah satunya. Kemudian empat cabang tambahan dibuat, misalnya, dengan nama orang-orang ini. Masing-masing bekerja secara lokal, di cabang sendiri dan membuat perubahan dengan semua
perintah git yang diperlukan.
Setelah menyelesaikan beberapa pekerjaan selesai, Anda membentuk permintaan tarik, sehingga memulai diskusi tentang perubahan Anda. Mungkin dalam proses diskusi, ternyata Anda harus menambah atau mengubah sesuatu yang lain. Dalam hal ini, Anda membuat perubahan yang diperlukan dan membuat permintaan tarik tambahan. Pada akhirnya, perubahan Anda diterima dan digabung dengan cabang master (atau ditolak).
Tentu saja, ini adalah deskripsi yang cukup umum. Saya sarankan menghubungi pengembang Anda atau menemukan orang yang berpengetahuan untuk membuat proses terperinci. Tetapi saya ingin mencatat bahwa ambang untuk memasuki Git cukup rendah. Ini tidak berarti bahwa protokolnya sederhana, tetapi Anda bisa mulai dengan yang sederhana. Jika Anda tidak tahu apa-apa, saya pikir, setelah menghabiskan beberapa jam atau mungkin berhari-hari untuk belajar dan menginstal, Anda dapat mulai menggunakannya.
Apa gunanya pendekatan ini sebagai perbandingan, misalnya, dengan proses yang dijelaskan dalam contoh di atas?
Bahkan, prosesnya sangat mirip, Anda baru saja diganti
menyalin file -> membuat cabang
salin teks ke file akhir-> gabung (gabung)
menyalin perubahan terbaru untuk diri sendiri -> git pull / fetch
diskusi dalam korespondensi -> tarik permintaan
mode track -> git diff
versi terbaru yang disetujui -> cabang utama
backup (menyalin ke server jauh) -> git push
...
Dengan demikian, Anda mengotomatiskan semua yang sudah Anda lakukan, tetapi secara manual.
Pada level yang lebih tinggi, ini memungkinkan Anda
- Buat proses yang jelas, sederhana, dan terkontrol untuk mengubah dokumentasi.
- karena dokumen akhir (dalam contoh kami MS Word) yang Anda buat secara otomatis, ini mengurangi kemungkinan kesalahan terkait dengan pemformatan
Komentar
Mengingat hal di atas, saya pikir sudah jelas bahwa bahkan jika Anda mengerjakan dokumentasi sendirian, menggunakan Git dapat sangat memudahkan pekerjaan Anda
Semua ini meningkatkan kualitas dokumentasi dan mengurangi waktu pembuatannya. Dan sedikit bonus - Anda belajar Git, yang akan membantu Anda mengotomatisasi jaringan Anda :)
Bagaimana cara beralih ke proses baru?
Di awal artikel, saya menulis bahwa besok Anda bisa mulai bekerja dengan cara baru. Bagaimana cara menerjemahkan pekerjaan Anda ke arah yang baru?
Berikut adalah urutan langkah-langkah yang kemungkinan besar harus Anda selesaikan:
- jika dokumen Anda sangat besar, pecahkan menjadi beberapa bagian
- konversi setiap bagian ke Penurunan harga (menggunakan Pandoc, misalnya)
- instal salah satu editor Markdown (saya menggunakan Typora )
- kemungkinan besar Anda harus mengubah format dokumen penurunan harga yang dibuat
- mulai menerapkan proses yang dijelaskan dalam bab sebelumnya
- paralel, mulailah memodifikasi skrip konversi agar sesuai dengan tugas Anda (atau buat sesuatu milik Anda sendiri)
Anda tidak perlu menunggu sampai Anda membuat dan men-debug dengan sempurna mekanisme konversi Markdwon -> yang diperlukan untuk tipe dokumen keluaran. Faktanya adalah bahwa bahkan jika Anda tidak dapat dengan cepat mengotomatiskan sepenuhnya konversi file Markdown Anda, Anda masih dapat melakukannya dalam bentuk apa pun menggunakan Pandoc dan kemudian membawanya secara manual ke bentuk akhirnya. Biasanya Anda tidak perlu sering melakukan ini, tetapi hanya pada akhir tahapan tertentu, dan pekerjaan manual ini, meskipun tidak nyaman, menurut saya, masih dapat diterima pada tahap debugging dan seharusnya tidak terlalu memperlambat proses.
Segala sesuatu yang lain (Penurunan harga, Git, Pandoc, Typora) sudah siap dan tidak memerlukan upaya atau waktu khusus untuk mulai bekerja dengan mereka.