คู่มือรูปแบบเอกสาร Bazel

รายงานปัญหา ดูแหล่งที่มา

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

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

เอกสาร Bazel ควรทําตามหลักการเหล่านี้

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

การเขียน

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

ส่วนหัว

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

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

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

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

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

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

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

ชื่อ

  • ใช้ตัวพิมพ์ใหญ่อย่างถูกต้อง เช่น บาเซลและ Starlark

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

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

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

ขอบเขตของหน้า

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

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

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

เรื่อง

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

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

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

  • หากกลุ่มเป้าหมายของคุณไม่ใช่ผู้ใช้ 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>
    • ไม่: รับความช่วยเหลือจาก command: พิมพ์ความช่วยเหลือและตัวเลือกสําหรับ "คําสั่ง"

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

สารบัญ

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

รหัส

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

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

โค้ดบล็อก

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

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

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