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

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

หลักการให้คำจำกัดความ

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

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

การเขียน

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

ส่วนหัว

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

  • เขียนส่วนหัวให้สั้นกระชับโดยมีความเหมาะสม วิธีนี้จะช่วยให้ใส่เอกสารได้พอดี โดยไม่ต้องห่อหุ้ม

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

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

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

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

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

ชื่อ

  • ใช้อักษรตัวพิมพ์ใหญ่กับคำนามที่เหมาะสม เช่น Bazel และ Starlark

    • ใช่: ในตอนท้ายของบิลด์ 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 พบทรัพยากร Dependency ที่ไม่สอดคล้องกับกฎนี้ Bazel จะแสดงข้อผิดพลาด

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

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

น้ำเสียง

เขียนด้วยน้ำเสียงที่เป็นมิตรต่อธุรกิจ

  • หลีกเลี่ยงการใช้ภาษาพูด การแปลวลีภาษาอังกฤษ แบบเจาะจงนั้นเป็นเรื่องยาก

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

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

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

ประเภทไฟล์

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

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

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

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

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

รายการ

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

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

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

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

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

สารบัญ

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

รหัส

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

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

โค้ดบล็อก

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

การจัดรูปแบบโค้ดแบบอินไลน์

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