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

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

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

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

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

การเขียน

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

ส่วนหัว

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

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

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

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

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

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

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

ชื่อ

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

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

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

น้ำเสียง

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

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

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

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

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

ประเภทไฟล์

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

ลิงก์

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

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

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

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

รายการ

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

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

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

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

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

สารบัญ

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

รหัส

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

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

โค้ดบล็อก

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

```shell
...

• แยกคำสั่งและเอาต์พุตออกเป็นโค้ดบล็อกต่างๆ

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

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