วิธีใช้:การทำเอกสารการใช้งานแม่แบบและมอดูล

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

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

* เอกสารการใช้งานที่ลอกมาจากภาษาอังกฤษ ไม่จำเป็นต้องแปลก็ได้ เพื่อประหยัดเวลา แต่จุดที่ควรแปลคือหมวดหมู่ *

สิ่งที่ต้องใส่

เอกสารการใช้งานควรครอบคลุม:

• หมวดหมู่ ถ้ามี สิ่งนี้ต้องอยู่ภายในแท็ก <includeonly>…</includeonly> มอดูลไม่สามารถจัดหมวดหมู่ได้ เว้นแต่ผ่านหน้าเอกสาร ดังนั้นสิ่งนี้จึงมีความสำคัญเป็นพิเศษสำหรับมอดูลเหล่านี้ ทุกมอดูลควรมีหน้าเอกสารพร้อมหมวดหมู่ แม้ว่าคุณจะ (ยัง) ไม่ได้เขียนเอกสารอื่น ๆ หมวดหมู่มีมากมายให้เลือก ดูที่ หมวดหมู่:แม่แบบ และ หมวดหมู่:มอดูล เพื่อเรียกดูหมวดหมู่ที่ต้องการ
• วัตถุประสงค์พื้นฐานของแม่แบบหรือมอดูล: มันทำหน้าที่อะไร และหากไม่ชัดเจนในทันที เหตุใดจึงต้องสร้างขึ้น หากมีแม่แบบหรือมอดูลอื่น ๆ ที่มีชื่อหรือวัตถุประสงค์คล้ายกัน ขอแนะนำว่าให้พูดถึงสิ่งเหล่านั้นด้วย เพื่อลดโอกาสของการใช้งานที่ไม่ถูกต้อง
• พารามิเตอร์ของแม่แบบหรือมอดูล: ไม่ว่าจะเป็นตัวเลข ชื่อ หรือที่เลือกได้ และถ้าใช่ ค่าเริ่มต้นคืออะไรและมีผลอย่างไร หากพารามิเตอร์รับได้เพียงชุดค่าที่จำกัดหรือถูกจำกัดด้วยวิธีการใด ๆ เช่น หากใช้ได้เฉพาะ: “ใช่” “ไม่ใช่” หรือตัวเลข ก็ควรอธิบายให้ชัดเจน
• ตัวอย่างการใช้งานของแม่แบบ: ระบุข้อความวิกิที่ควรใช้และผลลัพธ์ที่ได้ ข้อความวิกิสามารถอยู่ในแท็ก <code>…</code> เพื่อให้ชัดเจนและ ง่ายต่อการคัดลอก เช่นอย่างนี้ หากแม่แบบสามารถใช้ได้หลายวิธี โดยมีหรือไม่มีพารามิเตอร์เสริมเป็นต้น ให้แสดงตัวอย่างที่แตกต่างกันจำนวนหนึ่ง วิธีที่ดีในการทำเช่นนี้คือการรวมแม่แบบลงในเอกสารสักสองสามครั้ง (นั่นคือ ใช้ตัวอย่างสด) โดยใช้พารามิเตอร์ที่แตกต่างกันในแต่ละครั้ง และแสดงรายการพารามิเตอร์ที่ใช้ในแต่ละกรณี
• แม่แบบหรือมอดูลที่เกี่ยวข้อง: หากแม่แบบหรือมอดูลเป็นส่วนหนึ่งของชุดที่มีจุดประสงค์ร่วมกัน ให้ใส่ลิงก์ไปยังสิ่งเหล่านี้ โดยเฉพาะอย่างยิ่ง ตรวจสอบให้แน่ใจว่าทุกอันในชุดนั้นเชื่อมโยงถึงกัน ซึ่งจะทำให้การนำทางง่ายขึ้น

เอกสารการใช้งานถูกวางไว้ในหน้าย่อยของแม่แบบหรือมอดูลนั้น ๆ โดยต่อท้ายชื่อด้วย /documentation มอดูลจะถ่ายโอนหน้านี้ไปยังหน้ามอดูลหลักโดยอัตโนมัติ ส่วนแม่แบบไม่ทำเช่นนี้ ดังนั้นคุณต้องใช้แม่แบบ {{documentation}} เพื่อดำเนินการนี้ ซึ่งจะช่วยแยกรหัสแม่แบบที่มักจะซับซ้อนออกจากเอกสารการใช้งาน ทำให้แก้ไขเอกสารได้ง่ายขึ้น นอกจากนี้ยังอนุญาตให้มีการป้องกันแม่แบบเมื่อจำเป็น ในขณะที่ทุกคนสามารถแก้ไขเอกสารและหมวดหมู่ได้ ข้อความในหน้าแม่แบบนั้น ๆ จะเพิ่มจำนวนข้อความที่ต้องดำเนินการเมื่อแสดงแม่แบบ ซึ่งถูกจำกัดด้วยเหตุผลด้านประสิทธิภาพ การวางเอกสารในหน้าย่อยช่วยหลีกเลี่ยงสิ่งนี้ (ผู้พัฒนามีเดียวิกิได้แนะนำด้วยเหตุผลนี้)

วิธีสร้างหน้าย่อยของเอกสารการใช้งาน

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

สมมติว่าแม่แบบของคุณชื่อ แม่แบบ:X หรือมอดูลของคุณชื่อ มอดูล:X ให้สร้างหน้าย่อยที่มีชื่อว่า แม่แบบ:X/documentation หรือ มอดูล:X/documentation ดูรายละเอียดได้ที่ {{documentation subpage}} หรือคัดลอกและวางข้อความวิกิต่อไปนี้เพื่อเริ่มต้นเอกสารของคุณ:

{{documentation subpage}}
<!-- โปรดเพิ่มหมวดหมู่และลิงก์ข้ามวิกิที่ด้านล่างของหน้านี้ -->

== การใช้งาน ==

<includeonly><!-- วางหมวดหมู่และลิงก์ข้ามวิกิที่นี่ ขอบคุณ -->

</includeonly>

บรรทัดบนสุดจะแสดงข้อความอธิบายหน้าปัจจุบันและลิงก์ไปยังหน้าหลักของแม่แบบหรือมอดูล

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

ข้อมูลเพิ่มเติมสำหรับแม่แบบ

ในกรณีของแม่แบบ คุณจะต้องเพิ่มหน้าย่อยของเอกสารการใช้งานให้กับแม่แบบนั้นด้วย กลับไปที่หน้าหลักของแม่แบบ แม่แบบ:X ในตัวอย่างนี้ แก้ไขแม่แบบและต่อท้ายสิ่งต่อไปนี้ที่ส่วนท้ายของรหัสแม่แบบ:

[--บรรทัดสุดท้ายของรหัสแม่แบบของคุณ--]<noinclude>{{documentation}}</noinclude>

ซึ่งจะรวม {{documentation}} ไว้ที่ด้านล่างของหน้าแม่แบบ

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

หากแม่แบบได้รับการป้องกันอยู่ ให้ขอให้ผู้ดูแลระบบดำเนินการนี้หรือร้องขอให้แก้ไขในหน้าพูดคุยของแม่แบบ หากเอกสารการใช้งาน หมวดหมู่ และลิงก์ข้ามวิกิมีอยู่แล้วในส่วนที่อยู่ภายในแท็ก <noinclude>…</noinclude> ให้ย้ายลงในหน้าย่อยของเอกสารการใช้งาน เนื่องจากมันจะเป็นการดีที่สุดที่จะไม่แยกเอกสารออกเป็นสองหน้าแยกกัน

โปรดทราบว่าหากใส่แม่แบบ {{documentation}} ลงในหน้าแม่แบบก่อน ผู้ใช้จะได้รับประโยชน์จากคุณลักษณะโหลดล่วงหน้า (preload) เพื่อรับโครงร่างหน้าเอกสารที่กรอกไว้ล่วงหน้า หากยังไม่มีหน้าเอกสาร การคลิกลิงก์แก้ไขในหน้าแม่แบบจะโหลดเนื้อหาของ แม่แบบ:documentation/preloadTemplate ล่วงหน้าลงในช่องแก้ไขของการสร้างหน้าย่อย /documentation

หมวดหมู่และลิงก์ข้ามวิกิ

• การจัดแม่แบบหรือมอดูลลงในหมวดหมู่ ให้เพิ่มรหัส [[หมวดหมู่:ชื่อหมวดหมู่]] ภายในส่วน <includeonly>...</includeonly> ในหน้าย่อยของเอกสารการใช้งาน

• การสร้างลิงก์ข้ามวิกิสำหรับแม่แบบหรือมอดูลนั้น ๆ ให้เพิ่มรหัส [[รหัสภาษา:ชื่อแม่แบบ-มอดูล]] ภายในส่วน <includeonly>...</includeonly> ในหน้าย่อยของเอกสารการใช้งาน

• การจัดหน้าย่อยของเอกสารการใช้งานลงในหมวดหมู่ ให้เพิ่มรหัส [[หมวดหมู่:ชื่อหมวดหมู่]] ภายในส่วน <includeonly>...</includeonly> ในหน้าย่อยของเอกสารการใช้งาน

• การทำให้แม่แบบจัดบทความลงในหมวดหมู่ (เมื่อบทความมีแม่แบบ) ให้เพิ่มรหัส [[หมวดหมู่:ชื่อหมวดหมู่]] ภายในส่วน <includeonly>...</includeonly> ในหน้าแม่แบบ แต่สำหรับมอดูล สิ่งที่เทียบเท่าคือการ “ส่งคืน” (return) รหัสของหมวดหมู่ โดยเป็นส่วนหนึ่งของข้อความวิกิที่ส่งคืน

หลายแม่แบบ เอกสารหน้าเดียว

เมื่อหลายแม่แบบทำงานร่วมกันหรือคล้ายกันมาก มันจะชัดเจนและง่ายกว่าที่จะดูแลรักษาเอกสารการใช้งานหน้าเดียวซึ่งจัดทำไว้ด้วยกัน วิธีที่ง่ายที่สุดในการทำเช่นนี้คือ สร้างหน้าเอกสารฉบับเต็มในแม่แบบใดแม่แบบหนึ่ง แล้วสร้าง "การเปลี่ยนเส้นทาง" จากหน้าเอกสารประกอบของแม่แบบอื่น ดู แม่แบบ:nl-conj-wk และ แม่แบบ:nl-conj-st สำหรับตัวอย่างของหลักการนี้

ดูเพิ่ม

• {{documentation}} – รวมเอกสารการใช้งานบนหน้าแม่แบบ และสามารถดูเอกสาร แก้ไข และลิงก์ประวัติ
• {{documentation subpage}} – อธิบายว่าสิ่งที่ตามมาคือเอกสารการใช้งานและลิงก์ไปยังหน้าเอกสาร
• <noinclude> และ <includeonly>