ขอขอบคุณที่มีส่วนร่วมในเอกสารประกอบของ Bazel วิธีนี้เป็นคู่มือแนะนำ รูปแบบเอกสารฉบับย่อเพื่อช่วยในการเริ่มต้นใช้งาน สำหรับคำถามเรื่องสไตล์ที่คู่มือนี้ไม่ได้ให้คำตอบ โปรดทำตามคู่มือคำแนะนำเกี่ยวกับเอกสารประกอบสำหรับนักพัฒนาซอฟต์แวร์ Google
หลักการในการกำหนด
เอกสารของ Bazel ควรสนับสนุนหลักการเหล่านี้
- กระชับ ใช้คำให้น้อยที่สุดเท่าที่จะทำได้
- ล้าง ใช้ภาษาที่เข้าใจง่าย เขียนโดยไม่ใช้คำศัพท์เฉพาะ สำหรับระดับการอ่านชั้นประถมศึกษาปีที่ 5
- มีความสอดคล้อง ใช้คำหรือวลีเดียวกันสำหรับแนวคิดที่ซ้ำกันตลอดทั้งเอกสาร
- ถูกต้อง เขียนในลักษณะที่เนื้อหายังมีความถูกต้องอยู่นานที่สุดเท่าที่จะเป็นไปได้ โดยหลีกเลี่ยงการให้ข้อมูลที่อิงตามเวลาและคำสัญญาสำหรับอนาคต
การเขียน
ส่วนนี้ประกอบด้วยเคล็ดลับพื้นฐานในการเขียน
ส่วนหัว
- ส่วนหัวระดับหน้าเว็บจะเริ่มที่ H2 (ส่วนหัว H1 ใช้เป็นชื่อหน้า)
ทำให้ส่วนหัวสั้นและสมเหตุสมผล วิธีนี้ทำให้สามารถ อยู่ใน TOC ได้โดยไม่ต้องห่อ
- ใช่: สิทธิ์
- ไม่ใช่: หมายเหตุสั้นๆ เกี่ยวกับสิทธิ์
ขึ้นต้นประโยคด้วยตัวพิมพ์ใหญ่ หรือใช้ตัวพิมพ์ใหญ่กับอักษรตัวแรกของคำและวิสามานยนาม (สำหรับส่วนหัว)
- ใช่: ตั้งค่าพื้นที่ทํางาน
- ไม่: ตั้งค่าพื้นที่ทำงาน
โดยพยายามทำให้ส่วนหัวตรงตามงานหรือใช้งานได้ หากส่วนหัวมีแนวคิด อาจอิงจากความเข้าใจ แต่เขียนถึงสิ่งที่ผู้ใช้ทำ
- ใช่: การรักษาลำดับกราฟ
- ไม่: ใช้การเก็บรักษาลำดับกราฟ
ชื่อ
ทำให้คำนามที่เหมาะสมเป็นตัวพิมพ์ใหญ่ เช่น Bazel และ Starlark
- ใช่: เมื่อสิ้นสุดบิลด์ Bazel จะพิมพ์เป้าหมายที่ขอ
- ไม่: ในตอนท้ายของบิลด์ ให้พิมพ์เป้าหมายที่ขอ
รักษาความสม่ำเสมอ อย่าแนะนำชื่อใหม่สำหรับแนวคิดที่มีอยู่แล้ว ใช้คำที่ระบุไว้ในอภิธานศัพท์ ในกรณีที่เกี่ยวข้อง
- ตัวอย่างเช่น หากคุณกำลังเขียนเกี่ยวกับการออกคำสั่งบนเทอร์มินัล อย่าใช้ทั้งเทอร์มินัลและบรรทัดคำสั่งในหน้าดังกล่าว
ขอบเขตของหน้า
แต่ละหน้าควรมีวัตถุประสงค์เดียวและควรกำหนดไว้ที่ส่วนเริ่มต้น ซึ่งจะช่วยให้ผู้อ่านพบสิ่งที่ต้องการได้เร็วขึ้น
- ใช่: หน้านี้อธิบายวิธีติดตั้ง Bazel ใน Windows
- ไม่: (ไม่มีประโยคแนะนำ)
บอกผู้อ่านถึงสิ่งที่ต้องทำต่อไปในตอนท้ายของหน้า สําหรับหน้าที่ไม่มีการดําเนินการที่ชัดเจน คุณสามารถใส่ลิงก์ไปยังแนวคิดที่คล้ายกัน ตัวอย่าง หรือช่องทางอื่นๆ สําหรับการสำรวจได้
เรื่อง
ในเอกสารของ Bazel กลุ่มเป้าหมายควรเป็นผู้ใช้เป็นหลัก ซึ่งก็คือผู้ที่ใช้ Bazel ในการสร้างซอฟต์แวร์ของตน
เรียกผู้อ่านด้วยคำว่า "คุณ" (หากใช้คำว่า "คุณ" ไม่ได้ ให้ใช้ภาษาที่เป็นกลางทางเพศ เช่น ภาษาเหล่านั้น)
- ใช่: หากต้องการสร้างโค้ด Java โดยใช้ Bazel คุณต้องติดตั้ง JDK
- อาจ: ผู้ใช้จะต้องติดตั้ง 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]
รายการ
- ใช้รายการตามลำดับเพื่ออธิบายวิธีทำงานให้สำเร็จด้วยขั้นตอน
- ใช้รายการที่ไม่ได้เรียงลำดับเพื่อแสดงรายการที่ไม่ใช่งาน (ควรจะยังมีการเรียงลำดับ เช่น ตามลำดับตัวอักษร ความสำคัญ ฯลฯ)
- เขียนโดยใช้โครงสร้างแบบขนาน เช่น
- สร้างประโยคในรายการทั้งหมด
- เริ่มต้นด้วยคำกริยาที่เครียดเหมือนกัน
- ใช้รายการตามลำดับหากมีขั้นตอนที่ต้องปฏิบัติตาม
ตัวยึดตำแหน่ง
ใช้วงเล็บสามเหลี่ยมเพื่อแสดงตัวแปรที่ผู้ใช้ควรเปลี่ยนแปลง ในมาร์กดาวน์ ให้หลีกวงเล็บมุมด้วยเครื่องหมายทับย้อนกลับ:
\<example\>
- ใช่:
bazel help <command>
: ความช่วยเหลือ และตัวเลือกสำหรับการพิมพ์สำหรับ<command>
- ไม่: คำสั่งช่วยเหลือของ bazel: ความช่วยเหลือ และตัวเลือกสำหรับ "command"
- ใช่:
โดยเฉพาะอย่างยิ่งสำหรับตัวอย่างโค้ดที่ซับซ้อน ให้ใช้ตัวยึดตำแหน่งที่เหมาะสมในบริบท
สารบัญ
ใช้ TOC ที่สร้างขึ้นโดยอัตโนมัติที่เว็บไซต์รองรับ อย่าเพิ่ม TOC ด้วยตนเอง
โค้ด
ตัวอย่างโค้ดเป็นเพื่อนที่ดีที่สุดของนักพัฒนาซอฟต์แวร์ คุณอาจรู้วิธีเขียนข้อมูลเหล่านี้แล้ว แต่นี่เป็นเคล็ดลับเล็กๆ น้อยๆ
หากคุณกำลังอ้างอิงข้อมูลโค้ดสั้นๆ คุณสามารถฝังไว้ในประโยคได้ หากต้องการให้ผู้อ่านใช้โค้ด เช่น คัดลอกคำสั่ง ให้ใช้การบล็อกโค้ด
โค้ดบล็อก
- ตัวอย่างช่องควรมีขนาดสั้นๆ กำจัดข้อความที่ซ้ำซ้อนหรือไม่จำเป็นทั้งหมดออกจากตัวอย่างโค้ด
- ในมาร์กดาวน์ ให้ระบุประเภทของโค้ดบล็อกโดยเพิ่มภาษาของตัวอย่าง
```shell
...
- แยกคำสั่งและเอาต์พุตออกเป็นโค้ดบล็อกต่างๆ
การจัดรูปแบบโค้ดในบรรทัด
- ใช้รูปแบบโค้ดสำหรับชื่อไฟล์ ไดเรกทอรี เส้นทาง และโค้ดสั้นๆ
- ใช้การจัดรูปแบบโค้ดในบรรทัดแทนตัวเอียง "เครื่องหมายคำพูด" หรือการทำตัวหนา
- ใช่:
bazel help <command>
: ความช่วยเหลือ และตัวเลือกสำหรับการพิมพ์สำหรับ<command>
- ไม่: คำสั่งช่วยเหลือของ bazel: ความช่วยเหลือ และตัวเลือกสำหรับ "command"
- ใช่: