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

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

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

เอกสาร Bazel ควรยึดถือหลักการต่อไปนี้

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

การเขียน

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

ส่วนหัว

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

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

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

• ขึ้นต้นหัวข้อด้วยตัวพิมพ์ใหญ่

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

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

  • ใช่: คงลําดับกราฟไว้
  • ไม่: เกี่ยวกับการเก็บรักษาลําดับของกราฟ

ชื่อ

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

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

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

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

ขอบเขตหน้าเว็บ

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

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

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

เรื่อง

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

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

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

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

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

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

ขมับ

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

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

เครียด

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

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

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

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

น้ำเสียง

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

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

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

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

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

ประเภทไฟล์

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

ลิงก์

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

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

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

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

รายการ

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

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

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

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

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

สารบัญ

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

รหัส

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

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

โค้ดบล็อก

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

```shell
...

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

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

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