คู่มือสไตล์เอกสาร Bazel

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

หลักการในการกำหนด

เอกสารของ Bazel ควรสนับสนุนหลักการเหล่านี้

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

การเขียน

ส่วนนี้ประกอบด้วยเคล็ดลับพื้นฐานในการเขียน

ส่วนหัว

• ส่วนหัวระดับหน้าเว็บจะเริ่มที่ H2 (ส่วนหัว H1 ใช้เป็นชื่อหน้า)

• ทำให้ส่วนหัวสั้นและสมเหตุสมผล วิธีนี้ทำให้สามารถ อยู่ใน TOC ได้โดยไม่ต้องห่อ

  • ใช่: สิทธิ์
  • ไม่: หมายเหตุสั้นๆ เกี่ยวกับสิทธิ์

• ขึ้นต้นประโยคด้วยตัวพิมพ์ใหญ่ หรือใช้ตัวพิมพ์ใหญ่กับอักษรตัวแรกของคำและวิสามานยนาม (สำหรับส่วนหัว)

  • ใช่: ตั้งค่าพื้นที่ทํางาน
  • ไม่: ตั้งค่า Workspace

• โดยพยายามทำให้ส่วนหัวตรงตามงานหรือใช้งานได้ หากส่วนหัวมีแนวคิด อาจอิงจากความเข้าใจ แต่เขียนถึงสิ่งที่ผู้ใช้ทำ

  • ใช่: การรักษาลำดับกราฟ
  • ไม่: ใช้การเก็บรักษาลำดับกราฟ

ชื่อ

• ทำให้คำนามที่เหมาะสมเป็นตัวพิมพ์ใหญ่ เช่น Bazel และ Starlark

  • ใช่: เมื่อสิ้นสุดบิลด์ Bazel จะพิมพ์เป้าหมายที่ขอ
  • ไม่: เมื่อบิลด์เสร็จแล้ว bazel จะพิมพ์เป้าหมายที่ขอ

• คุณควรรักษาความสม่ำเสมอไว้ อย่าใช้ชื่อใหม่สำหรับแนวคิดที่มีอยู่ ใช้คําที่กําหนดไว้ในอภิธานศัพท์ หากมี

  • ตัวอย่างเช่น หากคุณกำลังเขียนเกี่ยวกับการออกคำสั่งบนเทอร์มินัล อย่าใช้ทั้งเทอร์มินัลและบรรทัดคำสั่งในหน้าดังกล่าว

ขอบเขตของหน้า

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

  • ใช่: หน้านี้อธิบายวิธีติดตั้ง Bazel ใน Windows
  • ไม่มี: (ไม่มีประโยคนำ)

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

เรื่อง

ในเอกสารประกอบของ Bazel กลุ่มเป้าหมายควรเป็นผู้ใช้เป็นหลัก ซึ่งก็คือผู้ที่ใช้ Bazel เพื่อสร้างซอฟต์แวร์

• เรียกผู้อ่านด้วยคำว่า "คุณ" (หากมีเหตุผลบางอย่างที่ทำให้ใช้คำว่า "คุณ" ไม่ได้ ให้ใช้ภาษาที่เป็นกลางทางเพศ เช่น ภาษาเหล่านั้น)

  • ใช่: หากต้องการสร้างโค้ด Java โดยใช้ Bazel คุณต้องติดตั้ง JDK
  • อาจ: ผู้ใช้จะต้องติดตั้ง JDK จึงจะสร้างโค้ด Java ด้วย Bazel ได้
  • ไม่: ผู้ใช้ต้องติดตั้ง JDK ก่อนจึงจะสร้างโค้ด Java ด้วย Bazel ได้

• หากกลุ่มเป้าหมายของคุณไม่ใช่ผู้ใช้ Bazel ทั่วไป ให้กำหนดกลุ่มเป้าหมายที่ตอนต้นของหน้าหรือในส่วน กลุ่มเป้าหมายอื่นๆ อาจรวมถึงผู้ดูแล ผู้ร่วมให้ข้อมูล ผู้ย้ายข้อมูล หรือบทบาทอื่นๆ

• หลีกเลี่ยงการใช้ "เรา" ในเอกสารของผู้ใช้ไม่มีผู้เขียน เพียงแค่บอกข้อมูลที่เป็นไปได้

  • ใช่: เมื่อ Bazel พัฒนาไป คุณควรอัปเดตฐานโค้ดเพื่อรักษาความสามารถในการทำงานร่วมกัน
  • ไม่ใช่: Bazel มีการพัฒนา และเราจะทำการเปลี่ยนแปลงกับ Bazel ซึ่งในบางครั้ง อาจใช้ร่วมกันไม่ได้และต้องมีการเปลี่ยนแปลงบางอย่างจากผู้ใช้ Bazel

ขมับ

หากเป็นไปได้ ให้หลีกเลี่ยงคำที่ปรับสิ่งต่างๆ ให้ทันเหตุการณ์ เช่น การอ้างอิงวันที่ที่เจาะจง (ไตรมาส 2 ปี 2022) หรือพูดว่า "ตอนนี้" "ปัจจุบัน" หรือ "เร็วๆ นี้" ข้อมูลเหล่านี้ล้าสมัยอย่างรวดเร็วและอาจไม่ถูกต้องหากเป็นการฉายภาพในอนาคต แต่ให้ระบุระดับเวอร์ชันแทน เช่น "Bazel X.x ขึ้นไปรองรับ<feature>" หรือลิงก์ปัญหาใน GitHub

• ใช่: Bazel 0.10.0 ขึ้นไปรองรับ การแคชระยะไกล
• ไม่: Bazel จะรองรับการแคชระยะไกลเร็วๆ นี้ ซึ่งน่าจะอยู่ในช่วงเดือนตุลาคม 2017

เครียด

• ใช้รูปแบบปัจจุบัน หลีกเลี่ยงความตึงเครียดในอดีตหรือในอนาคตเว้นแต่จะจำเป็นจริงๆ เพื่อความชัดเจน

  • ใช่: Bazel จะแสดงข้อผิดพลาดเมื่อพบทรัพยากร Dependency ที่ไม่เป็นไปตามกฎนี้
  • ไม่: หาก Bazel พบข้อกำหนดที่ไม่เป็นไปตามกฎนี้ Bazel จะแสดงข้อผิดพลาด

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

  • ใช่: Bazel เริ่มต้น X และใช้ เอาต์พุตเพื่อสร้าง Y
  • ไม่: Bazel จะเริ่มต้น X จากนั้นจะสร้าง Y ด้วยเอาต์พุต

น้ำเสียง

เขียนด้วยถ้อยคำที่เหมาะกับธุรกิจ

• หลีกเลี่ยงภาษาพูด การแปลวลีเฉพาะภาษาอังกฤษนั้นทำได้ยากกว่า

  • ใช่: กฎชุดดี
  • ไม่: แล้วชุดกฎที่ดีคืออะไร

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

การจัดรูปแบบ

ประเภทไฟล์

ตัดบรรทัดเมื่อถึง 80 อักขระเพื่อให้อ่านง่าย ลิงก์หรือข้อมูลโค้ดแบบยาวอาจยาวกว่านี้ได้ แต่ควรขึ้นบรรทัดใหม่ เช่น

ลิงก์

• ใช้ข้อความลิงก์ที่สื่อความหมายแทน "ที่นี่" หรือ "ด้านล่าง" วิธีนี้ทำให้สแกนเอกสารได้ง่ายขึ้นและเหมาะสำหรับโปรแกรมอ่านหน้าจอ

  • ใช่: โปรดดูรายละเอียดเพิ่มเติมที่ [การติดตั้ง Bazel]
  • ไม่: ดูรายละเอียดเพิ่มเติมได้[ที่นี่]

• หากเป็นไปได้ให้จบประโยคด้วยลิงก์

  • ใช่: ดูรายละเอียดเพิ่มเติมได้ที่ [ลิงก์]
  • ไม่: ดูข้อมูลเพิ่มเติมที่ [ลิงก์]

รายการ

• ใช้รายการตามลำดับเพื่ออธิบายวิธีทำงานให้สำเร็จด้วยขั้นตอน
• ใช้รายการที่ไม่มีลําดับเพื่อแสดงรายการที่ไม่ได้อิงตามงาน (ควรจะยังมีการเรียงลำดับ เช่น ตามลำดับตัวอักษร ความสำคัญ ฯลฯ)
• เขียนโดยใช้โครงสร้างแบบขนาน เช่น
  1. สร้างประโยคในรายการทั้งหมด
  2. เริ่มต้นด้วยคำกริยาที่เครียดเหมือนกัน
  3. ใช้รายการตามลำดับหากมีขั้นตอนที่ต้องปฏิบัติตาม

ตัวยึดตำแหน่ง

• ใช้วงเล็บสามเหลี่ยมเพื่อแสดงตัวแปรที่ผู้ใช้ควรเปลี่ยนแปลง ในมาร์กดาวน์ ให้หลีกวงเล็บมุมด้วยเครื่องหมายทับย้อนกลับ: \<example\>

  • ใช่: bazel help <command>: ความช่วยเหลือ และตัวเลือกสำหรับการพิมพ์สำหรับ <command>
  • ไม่: คำสั่งช่วยเหลือของ bazel: ความช่วยเหลือ และตัวเลือกสำหรับ "command"

• โดยเฉพาะสำหรับตัวอย่างโค้ดที่ซับซ้อน ให้ใช้ตัวยึดตําแหน่งที่สื่อความหมายในบริบท

สารบัญ

ใช้สารบัญที่สร้างขึ้นโดยอัตโนมัติซึ่งเว็บไซต์รองรับ อย่าเพิ่ม TOC ด้วยตนเอง

รหัส

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

หากคุณกำลังอ้างอิงข้อมูลโค้ดสั้นๆ คุณสามารถฝังไว้ในประโยคได้ หากต้องการให้ผู้อ่านใช้โค้ด เช่น คัดลอกคำสั่ง ให้ใช้การบล็อกโค้ด

โค้ดบล็อก

• ทำให้สั้น นำข้อความที่ซ้ำซ้อนหรือไม่จำเป็นทั้งหมดออกจากตัวอย่างโค้ด
• ในมาร์กดาวน์ ให้ระบุประเภทของโค้ดบล็อกโดยเพิ่มภาษาของตัวอย่าง

```shell
...

• แยกคำสั่งและเอาต์พุตออกเป็นโค้ดบล็อกต่างๆ

การจัดรูปแบบโค้ดในบรรทัด

• ใช้รูปแบบโค้ดสำหรับชื่อไฟล์ ไดเรกทอรี เส้นทาง และโค้ดสั้นๆ
• ใช้การจัดรูปแบบโค้ดในบรรทัดแทนตัวเอียง "เครื่องหมายคำพูด" หรือbolding
  • ใช่: bazel help <command>: ความช่วยเหลือ และตัวเลือกสำหรับการพิมพ์สำหรับ <command>
  • ไม่: bazel help command: แสดงความช่วยเหลือและตัวเลือกสำหรับ "command"