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

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

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

น้ำเสียง

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

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

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

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

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

ประเภทไฟล์

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

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

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

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

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

รายการ

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

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

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

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

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

สารบัญ

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

รหัส

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

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

โค้ดบล็อก

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

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

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