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

รายงานปัญหา ดูแหล่งที่มา รุ่น Nightly · 7.4 7.3 · 7.2 · 7.1 · 7.0 · 6.5

ขอขอบคุณที่มีส่วนร่วมในเอกสารประกอบของ 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. ใช้รายการแบบจัดลำดับหากมีขั้นตอนที่ต้องทำ

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

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

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

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

สารบัญ

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

รหัส

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

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

โค้ดบล็อก

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

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

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