🥇ใช้ GIT สำหรับการจัดทำเอกสาร

บางครั้งไม่เพียงแต่เอกสารประกอบเท่านั้น แต่ยังรวมถึงกระบวนการทำงานด้วยก็อาจมีความสำคัญเช่นกัน ตัวอย่างเช่น ในกรณีของโครงการ ส่วนแบ่งส่วนใหญ่ของงานเกี่ยวข้องกับการจัดเตรียมเอกสาร และกระบวนการที่ไม่ถูกต้องอาจนำไปสู่ข้อผิดพลาดและแม้กระทั่งการสูญเสียข้อมูล และผลที่ตามมาคือการสูญเสียเวลาและผลประโยชน์ แต่แม้ว่าหัวข้อนี้จะไม่ได้เป็นศูนย์กลางในการทำงานของคุณและอยู่บริเวณรอบนอก กระบวนการที่เหมาะสมยังสามารถปรับปรุงคุณภาพของเอกสารและช่วยคุณประหยัดเวลาได้

โดยมีแนวทางที่สรุปไว้ ณ ที่นี้ด้วย ตัวอย่างของการดำเนินการเฉพาะ, มีอุปสรรคในการเข้าต่ำ ในทางเทคนิคแล้ว คุณสามารถเริ่มทำงานในรูปแบบใหม่ได้ในวันพรุ่งนี้

คำแถลงปัญหา

คุณต้องสร้างเอกสารหรือชุดเอกสาร บางทีนี่อาจเป็นเอกสารโครงการหรือการบันทึกเครือข่ายของคุณ หรือสิ่งที่ง่ายกว่านั้น เช่น คุณต้องอธิบายกระบวนการในบริษัทหรือในแผนกของคุณ โดยทั่วไป เรากำลังพูดถึงเอกสารหรือชุดเอกสารใด ๆ ที่มีข้อความ รูปภาพ ป้าย... มาทำให้งานซับซ้อนขึ้นโดยข้อเท็จจริงที่ว่า

งานนี้เกี่ยวข้องกับการทำงานร่วมกันความพยายามของกลุ่มหรือพนักงานหลายกลุ่ม
ด้วยเหตุนี้ คุณจึงต้องการให้เอกสารอยู่ในรูปแบบที่กำหนด พร้อมด้วยคุณลักษณะสไตล์องค์กรที่สร้างขึ้นตามเทมเพลตที่กำหนด หากเจาะจง เราจะถือว่านี่คือ MS Word (.docx)

10 ปีที่แล้ว แนวทางนี้น่าจะตรงไปตรงมา: เราจะสร้างเอกสาร MS Word หรือเอกสารต่างๆ และจัดระเบียบงานการเปลี่ยนแปลงด้วยวิธีใดวิธีหนึ่ง

และแนวทางนี้ยังใช้ได้อยู่ ผู้รวมระบบรายใหญ่ยังใช้เมื่อสร้างเอกสารโครงการ แต่เป็นที่ชัดเจนโดยสัญชาตญาณว่าหากคุณทำงานอย่างเข้มข้นกับเอกสารที่มีการแก้ไขและการอภิปรายหลายครั้งเป็นเวลานาน วิธีนี้จะไม่สะดวกนัก

ตัวอย่าง
ฉันรู้สึกถึงปัญหานี้ค่อนข้างรุนแรงขณะทำงานให้กับผู้ประกอบระบบรายใหญ่ กระบวนการเปลี่ยนแปลงเอกสารการออกแบบมีดังนี้:

วิศวกรดาวน์โหลดเอกสาร MS Word (.docx) เวอร์ชันล่าสุด

เปลี่ยนชื่อ

ทำการเปลี่ยนแปลงเพื่อติดตามแฟชั่น

ส่งเอกสารพร้อมการแก้ไขไปให้สถาปนิก

ยังส่งรายการแก้ไขทั้งหมดพร้อมแสดงความคิดเห็นอีกด้วย

สถาปนิกวิเคราะห์การเปลี่ยนแปลง

หากทุกอย่างเรียบร้อยดี ระบบจะคัดลอกการเปลี่ยนแปลงเหล่านี้ไปยังไฟล์ที่เป็นเวอร์ชันล่าสุด เปลี่ยนเวอร์ชัน และอัปโหลดไปยังทรัพยากรที่ใช้ร่วมกัน

หากมีความคิดเห็น การสนทนาจะเริ่มขึ้น (อีเมลหรือการประชุม)

ฉันทามติถึงแล้ว

ประเด็นเพิ่มเติม 3 - 9
ถึงแม้งานจะไม่ค่อยเข้มข้นแต่ก็ยังได้ผล แต่เมื่อถึงจุดหนึ่ง กระบวนการนี้ก็กลายเป็นคอขวดของทั้งโครงการและนำไปสู่ปัญหา ประเด็นก็คือสิ่งต่างๆ จะแย่ทันทีที่มีการเปลี่ยนแปลงบ่อยครั้งและพร้อมกันโดยหลายทีม
ดังนั้น เมื่อเราย้ายไปยังขั้นตอนการทดสอบเบื้องต้น ปัญหาต่างๆ ก็เริ่มปรากฏขึ้น และแม้ว่าจะเป็นการเปลี่ยนแปลงเล็กๆ น้อยๆ แต่ก็จำเป็นต้องเปลี่ยนเอกสารบ่อยครั้ง - สี่ทีมที่แตกต่างกัน ทุกวัน เกือบจะพร้อมๆ กันพร้อมการอภิปราย การเปลี่ยนแปลงทั้งหมดนี้เกิดขึ้นโดยวิศวกรคนหนึ่ง - สถาปนิก ไฟล์การออกแบบโครงการมีขนาดใหญ่มาก และส่งผลให้สถาปนิกต้องทำงานหนักเกินไปกับงานประจำที่เกี่ยวข้องกับการคัดลอก แก้ไข ทำผิดพลาดมากมาย ต้องตรวจสอบทุกอย่างอีกครั้ง ส่งอีกครั้ง และโดยทั่วไปแล้วไฟล์นั้นใกล้เคียงกับ ความวุ่นวาย.
ในกรณีนี้แนวทางนี้ซึ่งเป็นแนวทางในการทำงานกับเอกสาร MS Word ทำงานด้วยความยากลำบากอย่างมากและสร้างปัญหาขึ้นมา

กิต, มาร์กดาวน์

เมื่อต้องเผชิญกับปัญหาที่อธิบายไว้ในตัวอย่างข้างต้น ฉันจึงเริ่มค้นคว้าปัญหานี้
ผมเห็นว่าการใช้ Markdown ร่วมกับ ไป เมื่อสร้างเอกสาร

Git เป็นเครื่องมือในการพัฒนา แต่ทำไมไม่ใช้มันสำหรับกระบวนการเอกสารล่ะ? ในกรณีนี้ ปัญหาการทำงานของผู้ใช้หลายคนจะได้รับการแก้ไข แต่เพื่อที่จะใช้ประโยชน์จากความสามารถของ Git ได้อย่างเต็มที่ เราจำเป็นต้องมีรูปแบบเอกสารข้อความ เราจำเป็นต้องค้นหาเครื่องมืออื่นที่ไม่ใช่ MS Word และ Markdown ก็เหมาะสำหรับวัตถุประสงค์เหล่านี้

Markdown เป็นภาษามาร์กอัปข้อความธรรมดา ได้รับการออกแบบมาเพื่อสร้างข้อความที่ออกแบบมาอย่างสวยงามในไฟล์ TXT ปกติ หากเราสร้างเอกสารของเราใน Markdown ชุดค่าผสม Markdown - Git จะดูเป็นธรรมชาติ

และทุกอย่างจะเรียบร้อยดี และ ณ จุดนี้เราสามารถยุติมันได้ หากไม่ใช่เพราะเงื่อนไขที่สองของเรา: “ด้วยเหตุนี้ เราจึงจำเป็นต้องมีเอกสารในรูปแบบที่แน่นอน พร้อมด้วยคุณลักษณะของรูปแบบองค์กรที่สร้างขึ้นตาม เทมเพลตบางอย่าง” (และเราตกลงกันตั้งแต่ต้นว่าแน่นอนว่ามันจะเป็น MS Word) นั่นคือหากเราตัดสินใจใช้ Markdown เราจำเป็นต้องแปลงไฟล์นี้เป็น .docx ประเภทที่ต้องการ

มีโปรแกรมสำหรับแปลงระหว่างรูปแบบต่างๆ เช่น Pandoc.
คุณสามารถแปลงไฟล์ Markdown เป็นรูปแบบ .docx ด้วยโปรแกรมนี้
แต่ถึงกระนั้นคุณต้องเข้าใจว่าประการแรกไม่ใช่ทุกสิ่งที่อยู่ใน Markdown จะถูกแปลงเป็น MS Word และประการที่สอง MS Word เป็นทั้งประเทศเมื่อเทียบกับ Markdown ที่เรียวยาว แต่ยังคงเป็นเมืองเล็ก ๆ มีทุกสิ่งที่อยู่ใน Word จำนวนมากซึ่งไม่ได้อยู่ในรูปแบบใด ๆ ใน Markdown คุณไม่สามารถแปลงรูปแบบ Markdown ของคุณเป็นรูปแบบ MS Word ที่ต้องการได้โดยใช้ปุ่ม Pandoc บางปุ่ม โดยปกติ หลังจากการแปลง คุณจะต้อง “แก้ไข” เอกสาร .docx ที่ได้ผลลัพธ์ด้วยตนเอง ซึ่งอาจใช้เวลานานและนำไปสู่ข้อผิดพลาดอีกครั้ง

หากเราสามารถเขียนสคริปต์ที่จะ "เสร็จสิ้น" สิ่งที่ Pandoc ไม่สามารถจัดการได้โดยอัตโนมัติ นั่นจะเป็นทางออกที่ดี

เนื่องจากความไม่ระบุตัวตนของฟังก์ชันการทำงานของ MS Word และ Markdown ฉันคิดว่าโดยทั่วไปจึงเป็นไปไม่ได้ที่จะแก้ไขปัญหานี้ แต่สามารถทำได้โดยเกี่ยวข้องกับสถานการณ์เฉพาะข้อกำหนดเฉพาะหรือไม่ ประสบการณ์ของฉันแสดงให้เห็นว่า ใช่ เป็นไปได้ และมีแนวโน้มว่าจะเป็นไปได้สำหรับหลาย ๆ คนหรืออาจจะเป็นเกือบทุกสถานการณ์ด้วยซ้ำ

การแก้ปัญหาเฉพาะ

ดังนั้น ในกรณีของฉัน หลังจากแปลงไฟล์โดยใช้ Pandoc แล้ว ฉันต้องทำการประมวลผลไฟล์เพิ่มเติมด้วยตนเอง กล่าวคือ

เพิ่มฟิลด์ลงใน Word ด้วยการกำหนดหมายเลขหัวเรื่อง (คำบรรยาย) ของตารางและรูปภาพโดยอัตโนมัติ
เปลี่ยนสไตล์ตาราง

ฉันไม่พบวิธีการทำเช่นนี้โดยใช้มาตรฐาน (Pandoc) หรือวิธีที่รู้จัก ดังนั้นฉันจึงใช้สคริปต์ python ด้วย ไพวิน32 บรรจุุภัณฑ์. เป็นผลให้ฉันได้รับระบบอัตโนมัติเต็มรูปแบบ ตอนนี้ฉันสามารถแปลงไฟล์ Markdown เป็นรูปแบบเอกสาร MS Word ที่ต้องการได้ด้วยคำสั่งเดียว

ดูรายละเอียด ที่นี่.

คำพูด
ในตัวอย่างนี้ แน่นอนว่าฉันจะแปลงไฟล์ Markdown แบบนามธรรม แต่ใช้วิธีการเดียวกันนี้กับเอกสาร "การต่อสู้" และผลลัพธ์ที่ฉันได้รับนั้นเกือบจะเหมือนกับเอกสาร MS Word ที่เราได้รับก่อนหน้านี้จากการจัดรูปแบบด้วยตนเอง .

โดยทั่วไปแล้ว ด้วย pywin32 เราจึงสามารถควบคุมเอกสาร MS Word ได้เกือบทั้งหมด ซึ่งช่วยให้เราสามารถเปลี่ยนแปลงและจัดรูปแบบให้อยู่ในรูปแบบที่มาตรฐานองค์กรของคุณต้องการได้ แน่นอนว่าเป้าหมายเดียวกันนี้สามารถทำได้โดยใช้เครื่องมืออื่นๆ เช่น มาโคร VBA แต่การใช้ python จะสะดวกกว่าสำหรับฉัน

สูตรโดยย่อสำหรับแนวทางนี้:

Markdown + Git -- (нечто) --> MS Word

มันไม่สำคัญว่า "บางสิ่ง" คืออะไร ในกรณีของฉันมันคือ Pandoc และ python พร้อม pywin32 ความชอบของคุณอาจแตกต่างกัน แต่สิ่งสำคัญคือเป็นไปได้ และนี่คือข้อความหลักของบทความนี้

โดยสรุป แนวคิดก็คือด้วยวิธีนี้ คุณจะทำงานได้เฉพาะกับไฟล์ Markdown และใช้ Git สำหรับการทำงานร่วมกันและการควบคุมเวอร์ชัน และเมื่อจำเป็นเท่านั้น (เช่น เพื่อจัดเตรียมเอกสารประกอบให้กับลูกค้า) จะสร้างไฟล์ในรูปแบบที่ต้องการโดยอัตโนมัติ ( เช่น MS Word )

กระบวนการ

ฉันคิดว่าสำหรับหลาย ๆ คน สูตรที่ให้ไว้ข้างต้นเพียงพอที่จะเข้าใจว่าขณะนี้สามารถจัดระเบียบกระบวนการทำงานกับเอกสารได้อย่างไร แต่ถึงกระนั้น ฉันมักจะมุ่งเน้นไปที่วิศวกรเครือข่าย ดังนั้นฉันจะแสดงในแง่ทั่วไปว่ากระบวนการทำงานขณะนี้มีลักษณะอย่างไร และสิ่งนี้แตกต่างจากวิธีการแก้ไขไฟล์ MS Word อย่างไร

โดยเจาะจง เราจะเลือก GitHub เป็นแพลตฟอร์มสำหรับการทำงานกับ Git จากนั้นคุณควรสร้างพื้นที่เก็บข้อมูลและวางไฟล์ Markdown หรือไฟล์ที่คุณวางแผนจะใช้งานในสาขาหลัก

เราจะดูกระบวนการง่ายๆ ตาม "โฟลว์ github" คำอธิบายสามารถพบได้ทั้งบนอินเทอร์เน็ตและบน ฮาเบอร์.

สมมติว่ามีสี่คนที่ทำงานเกี่ยวกับเอกสารและคุณเป็นหนึ่งในนั้น จากนั้นจะมีการสร้างสาขาเพิ่มเติมอีก 4 สาขาด้วยชื่อของบุคคลเหล่านี้ ทุกคนทำงานในพื้นที่ ในสาขาของตนเอง และทำการเปลี่ยนแปลงโดยจำเป็นทั้งหมด คำสั่งคอมไพล์.

เมื่อทำงานเสร็จสมบูรณ์แล้ว คุณจะสร้างคำขอดึง ซึ่งจะเป็นการเริ่มต้นการอภิปรายเกี่ยวกับการเปลี่ยนแปลงของคุณ บางทีในระหว่างการสนทนา ปรากฎว่าคุณควรเพิ่มหรือเปลี่ยนแปลงอย่างอื่น ในกรณีนี้ คุณทำการเปลี่ยนแปลงที่จำเป็น และสร้างคำขอดึงเพิ่มเติม ในที่สุด การเปลี่ยนแปลงของคุณจะได้รับการยอมรับและรวมเข้ากับสาขาหลัก (หรือละทิ้ง)

แน่นอนว่านี่เป็นคำอธิบายที่ค่อนข้างทั่วไป หากต้องการสร้างกระบวนการโดยละเอียด ฉันขอแนะนำให้ติดต่อนักพัฒนาซอฟต์แวร์ของคุณหรือค้นหาบุคคลที่มีความรู้ แต่ฉันต้องการทราบว่าอุปสรรคในการเข้าสู่ Git นั้นค่อนข้างต่ำ นี่ไม่ได้เป็นการบอกว่าโปรโตคอลนั้นเรียบง่าย แต่คุณสามารถเริ่มต้นได้ง่ายๆ หากคุณไม่รู้อะไรเลย ฉันคิดว่าหลังจากใช้เวลาสองสามชั่วโมงหรือหลายวันในการเรียนรู้และติดตั้ง คุณก็สามารถเริ่มใช้งานได้

ประโยชน์ของแนวทางนี้คืออะไรเมื่อเปรียบเทียบกับกระบวนการที่อธิบายไว้ในตัวอย่างข้างต้น เช่น

ในความเป็นจริงกระบวนการค่อนข้างคล้ายกันคุณเพิ่งเปลี่ยนใหม่

คัดลอกไฟล์ -> สร้างสาขา
คัดลอกข้อความไปยังไฟล์สุดท้าย -> การรวม
คัดลอกการเปลี่ยนแปลงล่าสุดให้กับตัวคุณเอง -> git pull/fetch
การสนทนาทางจดหมาย -> คำขอดึง
โหมดติดตาม -> git diff
เวอร์ชันที่ได้รับการอนุมัติล่าสุด -> สาขาหลัก
สำรองข้อมูล (คัดลอกไปยังเซิร์ฟเวอร์ระยะไกล) -> git push
...

ดังนั้นคุณจึงทำให้ทุกสิ่งที่คุณต้องทำอยู่แล้วเป็นแบบอัตโนมัติ แต่เป็นด้วยตนเอง

ในระดับที่สูงขึ้นจะช่วยให้คุณ

สร้างกระบวนการเปลี่ยนแปลงเอกสารที่ชัดเจน เรียบง่าย และควบคุมได้
เพราะ คุณสร้างเอกสารขั้นสุดท้าย (ในตัวอย่าง MS Word ของเรา) โดยอัตโนมัติ ซึ่งจะช่วยลดโอกาสที่จะเกิดข้อผิดพลาดในการจัดรูปแบบ

คำพูด
ถึงอย่างนั้น ฉันคิดว่ามันชัดเจนว่าแม้ว่าคุณจะทำงานเกี่ยวกับเอกสารเพียงอย่างเดียว การใช้ Git จะทำให้งานของคุณง่ายขึ้นมาก

ทั้งหมดนี้ช่วยปรับปรุงคุณภาพของเอกสารและลดเวลาในการสร้าง และโบนัสเล็กๆ น้อยๆ อีกอย่าง - คุณจะได้เรียนรู้ Git ซึ่งจะช่วยคุณในการทำให้เครือข่ายของคุณเป็นแบบอัตโนมัติ :)

จะเปลี่ยนไปใช้กระบวนการใหม่ได้อย่างไร?

ในตอนต้นของบทความฉันเขียนว่าพรุ่งนี้คุณสามารถเริ่มทำงานในรูปแบบใหม่ได้ จะนำงานของคุณไปในทิศทางใหม่ได้อย่างไร?

นี่คือลำดับขั้นตอนที่คุณอาจต้องปฏิบัติตามมากที่สุด:

หากเอกสารของคุณมีขนาดใหญ่มาก ให้แบ่งออกเป็นส่วนๆ
แปลงแต่ละส่วนเป็น Markdown (โดยใช้ตัวอย่าง Pandoc)
ติดตั้งหนึ่งในเครื่องมือแก้ไข Markdown (ฉันใช้ Typora)
เป็นไปได้มากว่าคุณจะต้องปรับการจัดรูปแบบของเอกสาร Markdown ที่สร้างขึ้น
เริ่มใช้กระบวนการที่อธิบายไว้ในบทที่แล้ว
ในเวลาเดียวกัน ให้เริ่มแก้ไขสคริปต์การแปลงให้เหมาะกับงานของคุณ (หรือสร้างบางอย่างของคุณเอง)

คุณไม่จำเป็นต้องรอจนกว่าคุณจะสร้างและปรับปรุงกลไกการแปลง Markdwon -> ประเภทเอาต์พุตที่ต้องการของเอกสาร ประเด็นก็คือแม้ว่าคุณจะไม่สามารถดำเนินการขั้นตอนการแปลงไฟล์ Markdown ของคุณโดยอัตโนมัติได้อย่างรวดเร็ว แต่คุณยังคงสามารถทำได้ในบางรูปแบบโดยใช้ Pandoc จากนั้นนำไปที่รูปแบบสุดท้ายด้วยตนเอง โดยปกติแล้วคุณไม่จำเป็นต้องทำเช่นนี้บ่อยๆ แต่เฉพาะเมื่อสิ้นสุดบางขั้นตอนเท่านั้น และในความคิดของฉัน การทำงานด้วยตนเองนี้ แม้ว่าจะไม่สะดวก แต่ก็ยังค่อนข้างยอมรับได้ในขั้นตอนการดีบักและไม่ควร "ทำให้ช้าลง" กระบวนการ มาก.

ทุกอย่างอื่น (Markdown, Git, Pandoc, Typora) พร้อมแล้วและไม่ต้องใช้ความพยายามหรือเวลาในการเริ่มทำงานมากนัก

ที่มา: will.com