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

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

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

เอกสารประกอบของ Bazel ควรยึดตามหลักการต่อไปนี้

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

การเขียน

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

ส่วนหัว

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

• สร้างส่วนหัวให้สั้นที่สุดเท่าที่จะทำได้ เพื่อให้ส่วนหัวพอดีกับสารบัญโดยไม่ขึ้นบรรทัดใหม่

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

• ใช้ตัวพิมพ์เล็กสำหรับส่วนหัว

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

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

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

ชื่อ

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

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

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

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

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

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

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

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

เรื่อง

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

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

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

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

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

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

Temporal

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

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

กาล

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

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

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

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

น้ำเสียง

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

• หลีกเลี่ยงภาษาพูด เนื่องจากวลีที่เป็นภาษาอังกฤษโดยเฉพาะจะแปลได้ยากขึ้น

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

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

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

ประเภทไฟล์

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

ลิงก์

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

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

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

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

รายการ

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

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

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

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

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

สารบัญ

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

รหัส

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

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

โค้ดบล็อก

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

```shell
...

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

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

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