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

รายงานปัญหา ดูแหล่งที่มา Nightly · 8.4 · 8.3 · 8.2 · 8.1 · 8.0 · 7.6

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

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

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

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

การเขียน

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

ส่วนหัว

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

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

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

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

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

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

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

ชื่อ

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

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

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

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

ขอบเขตระดับหน้า

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

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

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

เรื่อง

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

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

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

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

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

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

Temporal

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

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

เครียด

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

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

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

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

น้ำเสียง

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

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

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

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

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

ประเภทไฟล์

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

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

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

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

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

รายการ

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

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

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

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

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

สารบัญ

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

รหัส

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

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

โค้ดบล็อก

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

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

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