ข้อมูลสำคัญของ Git และ GitHub สำหรับ Docs

ภาพรวม

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

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

GitHub เป็นบริการโฮสต์พื้นที่เก็บ Git บนเว็บ เช่น พื้นที่เก็บเนื้อหา docs.microsoft.com สำหรับทุกโครงการ GitHub โฮสต์ที่เก็บข้อมูลหลัก ซึ่งผู้ร่วมทำงานสามารถทำสำเนางานของตนเองได้จากที่นี่

Git

ถ้าคุณคุ้นเคยกับระบบควบคุมแบบรวมศูนย์ (เช่น Team Foundation Server, SharePoint หรือ Visual SourceSafe) คุณจะพบว่า Git มีเวิร์กโฟลว์และคำศัพท์การทำงานร่วมกันที่เป็นเอกเทศเพื่อสนับสนุนรูปแบบการกระจายเนื้อหา ตัวอย่างเช่น ไม่มีการล็อคไฟล์ที่มักเกี่ยวข้องกับการดำเนินการเช็คเอาท์/เช็คอิน แท้ที่จริง Git ให้ความใส่ใจกับการเปลี่ยนแปลงในระดับดียิ่งขึ้นโดยเปรียบเทียบไฟล์ทีละไบต์

Git ยังใช้โครงสร้างแบบชั้นพื่อจัดเก็บและจัดการเนื้อหาสำหรับโครงการ:

• พื้นที่เก็บ: หรือที่เรียกว่า repo ซึ่งเป็นหน่วยสูงสุดของการเก็บข้อมูล ที่เก็บประกอบด้วยสาขาหนึ่งสาขาหรือมากกว่า
• สาขา: หน่วยเก็บข้อมูลที่ประกอบด้วยไฟล์และโฟลเดอร์ที่ประกอบด้วยชุดเนื้อหาของโครงการ สาขาแยกสตรีมของงาน (โดยทั่วไปจะเรียกว่าเวอร์ชัน) จะมีการจัดใส่ข้อมูลและจัดขอบเขตในสาขาหนึ่งๆ พื้นที่เก็บข้อมูลทั้งหมดประกอบด้วยสาขาเริ่มต้น (โดยปกติจะมีชื่อว่า "หลัก") หนึ่งสาขาหรือมากกว่าที่ถูกปลายทางให้รวมกันเป็นสาขาเริ่มต้น สาขาเริ่มต้นใช้เป็นเวอร์ชันปัจจุบันและ "แหล่งความจริงเพียงแหล่งเดียว" ของโครงการ สาขาหลักเป็นตัวแม่ที่สร้างสาขาอื่นๆ ทั้งหมดในที่เก็บ

ผู้ร่วมสร้างข้อมูลในโครงการจะทำการโต้ตอบกับ Git เพื่อปรับปรุงและจัดการพื้นที่เก็บในระดับท้องถิ่นและระดับ GitHub

• โดยใช้เครื่องมือต่างๆ เช่น คอนโซล Git Bash ซึ่งสนับสนุนสั่ง Git เพื่อจัดการพื้นที่เก็บข้อมูลภายในเครื่อง และติดต่อสื่อสารกับGitHubเก็บข้อมูลปัจจุบัน
• ผ่านทาง www.github.comที่รวม Git เพื่อจัดการการรวบรวมการมีส่วนสนับสนุนที่ไหลกลับลงในที่เก็บหลัก

GitHub

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

ไดเรกทอรีองค์กร

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

โดยทั่วไป คุณสามารถค้นหา articles ไดเรกทอรี่หลักจากรากของที่เก็บ ไดเรกทอรีบทความประกอบด้วยชุดของไดเรกทอรีย่อย บทความในไดเรกทอรีย่อยถูกจัดรูปแบบเป็นไฟล์ Markdown ที่ใช้นามสกุล .md พื้นที่เก็บบางอย่างซึ่งสนับสนุนบริการหลายรายการ /articles ใช้ไดเรกทอรีย่อยทั่วไป เช่น/articles พื้นที่เก็บ IntunsDocs อาจใช้ชื่อบริการเฉพาะ เช่น ที่เก็บ IntunsDocs ซึ่งใช้

ภายในรากของไดเรกทอรีนี้ คุณสามารถค้นหาบทความทั่วไปที่เกี่ยวข้องกับบริการหรือผลิตภัณฑ์โดยรวม และโดยทั่วไปแล้ว คุณจะพบชุดไดเร็กทอรีย่อยอื่นๆ ที่ตรงกับคุณลักษณะ/บริการหรือสถานการณ์ทั่วไป ตัวอย่างเช่น บทความ "เครื่องเสมือน" Azure อยู่ใน /virtual-machines ไดเรกทอรีย่อยและบทความ "เข้าใจและสำรวจ" ของ Intune อยู่ใน /understand-explore ไดเรกทอรีย่อย

ไดเรกทอรีย่อยของสื่อ

แต่ละไดเร็กทอรีบทความประกอบด้วยไดเรกทอรีย่อย/media สำหรับไฟล์สื่อที่เกี่ยวข้อง ไฟล์สื่อที่ประกอบด้วยรูปที่บทความใช้โดยอ้างอิงถึงรูปนั้น

รวมไดเรกทอรีย่อย

เมื่อใดก็ตามที่เรามีเนื้อหาที่นำมาใช้ซ้ำได้ซึ่งใช้ร่วมกันในบทความสองชิ้นหรือมากกว่า เนื้อหานี้จะอยู่ใน/includesไดเรกทอรีย่อยจากไดเรกทอรีหลัก articles ในไฟล์ Markdown ที่ใช้ไฟล์รวมส่วนขยาย Markdown "รวม" ที่เกี่ยวข้องจะอยู่ในตำแหน่งที่อ้างถึงไฟล์ "รวม" นั้น

ดู การอ้างอิง Markdown: รวมสําหรับ การแนะนําเพิ่มเติม

เท็มเพลตไฟล์ Markdown

เพื่อความสะดวก ไดเรกทอรีรากของที่เก็บแต่ละแห่งมักมีไฟล์เทมเพลต Markdown ชื่อ template.md คุณสามารถใช้ไฟล์เทมเพลตนี้เป็น "ไฟล์เริ่มต้น" หากต้องการสร้างบทความใหม่เพื่อส่งไปยังที่เก็บ ไฟล์ประกอบด้วย:

• ส่วนหัวของเมตาดาต้า ที่ด้านบนของไฟล์ซึ่งมีตัวขีดกลาง 3 ตัวที่ถูกขีดเส้นใต้สองเส้น ส่วนหัวนี้ประกอบด้วยแท็กต่างๆ ที่ใช้ในการติดตามข้อมูลที่เกี่ยวข้องกับบทความ เมตาดาต้าของบทความทำให้ใช้งานฟังก์ชันบางอย่าง เช่น การระบุแหล่งที่มาของผู้เขียน การระบุแหล่งที่มาผู้ร่วมสร้างโครงการ และคำอธิบายบทความ นอกจากนี้ ยังรวมถึงการเพิ่มประสิทธิภาพ SEO และกระบวนการรายงานที่ Microsoft ใช้เพื่อประเมินประสิทธิภาพของเนื้อหา ดังนั้น เมตาดาต้าจึงเป็นสิ่งสำคัญ
• ส่วนเมตาดาต้า ที่อธิบายแท็กและค่าเมตาดาต้าต่างๆ ถ้าคุณไม่แน่ใจว่าควรใช้ค่าใดในส่วนเมตาดาต้า คุณสามารถปล่อยว่างไว้ หรือแสดงข้อคิดเห็นโดยวางแฮชแท็ก (#) ข้างหน้า และค่านั้นจะถูกตรวจทาน/กรอกให้สมบูรณ์โดยผู้ตรวจทานคำขอดึงข้อมูลสำหรับที่เก็บ
• ตัวอย่างต่างๆ ของการใช้ Markdown เพื่อจัดรูปแบบ elements ของบทความ
• คำแนะนำเกี่ยวกับการใช้ส่วนขยาย Markdown ซึ่งคุณสามารถใช้สำหรับการแจ้งเตือนชนิดต่างๆ
• ตัวอย่างของฝังวิดีโอโดยใช้ iframe
• คำแนะนำเกี่ยวกับการใช้ส่วนขยาย docs.microsoft.com ซึ่งคุณสามารถใช้เพื่อตัวควบคุมพิเศษ เช่น ปุ่มและตัวเลือก

คำขอดึงข้อมูล

คำขอดึงข้อมูลเป็นวิธีที่สะดวกสำหรับผู้ร่วมโครงการในการเสนอการเปลี่ยนแปลงที่จะมีผลกับสาขาเริ่มต้น การเปลี่ยนแปลง (หรือที่เรียกว่าบันทึก (commits)) จะถูกเก็บในสาขาของผู้ร่วมโครงการ ดังนั้น GitHub จะสามารถจำลองผลของการผสานการเปลี่ยนแปลงเหล่านี้ี้เข้ากับสาขาเริ่มต้น คำร้องขอการดึงข้อมูลยังทำหน้าที่เป็นกลไกที่ให้ข้อมูลป้อนกลับแก่ผู้ร่วมโครงการจากกระบวนการสร้าง/ตรวจสอบความถูกต้องและผู้พิจารณาคำขอดึงข้อมูล เพื่่อแก้ไขปัญหาหรือตอบคำถามที่อาจเกิดขึ้นก่อนที่การเปลี่ยนแปลงถูกผสานเข้าไปในสาขาเริ่มต้น

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