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

วันที่ รายงานปัญหา ดูแหล่งที่มา ตอนกลางคืน · 7.3 · 7.2 · 7.1 · 7.0 · 6.5

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

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

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

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

การเขียน

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

ส่วนหัว

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

  • ทำให้ส่วนหัวสั้นและสมเหตุสมผล ด้วยวิธีนี้ พวกเขาจะได้เข้าร่วม TOC โดยไม่ต้องตัดข้อความ

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

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

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

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

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

ชื่อ

  • ทำให้คำนามที่เหมาะสมเป็นตัวพิมพ์ใหญ่ เช่น Bazel และ Starlark

    • ใช่: เมื่อสิ้นสุดบิลด์ 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
    • ไม่ใช่: X เริ่มต้นโดย Bazel จากนั้น หลังจากนั้น Y จะสร้างขึ้นด้วยเอาต์พุต

น้ำเสียง

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

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

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

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

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

ประเภทไฟล์

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

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

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

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

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

รายการ

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

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

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

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

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

สารบัญ

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

รหัส

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

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

โค้ดบล็อก

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

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

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