เอกสารประกอบซอฟต์แวร์ที่ดี ไม่ว่าจะเป็นเอกสารข้อกำหนดสำหรับโปรแกรมเมอร์และผู้ทดสอบ เอกสารทางเทคนิคสำหรับผู้ใช้ภายใน หรือคู่มือและไฟล์ช่วยเหลือสำหรับผู้ใช้ จะช่วยให้ผู้ใช้เข้าใจคุณลักษณะและฟังก์ชันของซอฟต์แวร์ เอกสารที่ดีคือเอกสารที่มีความเฉพาะเจาะจง ชัดเจน และมีความเกี่ยวข้อง พร้อมด้วยข้อมูลทั้งหมดที่ผู้ใช้ต้องการ บทความนี้จะแนะนำคุณในการเขียนเอกสารซอฟต์แวร์สำหรับผู้ใช้ด้านเทคนิคและผู้ใช้ปลายทาง
ขั้นตอน
วิธีที่ 1 จาก 2: การเขียนเอกสารซอฟต์แวร์สำหรับผู้ใช้ทางเทคนิค
ขั้นตอนที่ 1 รู้ว่าจะรวมข้อมูลใดบ้าง
เอกสารข้อมูลจำเพาะใช้เป็นคู่มืออ้างอิงสำหรับนักออกแบบส่วนต่อประสาน โปรแกรมเมอร์ที่เขียนโค้ด และผู้ทดสอบที่ตรวจสอบประสิทธิภาพของซอฟต์แวร์ ข้อมูลที่จำเป็นต้องรวมจะขึ้นอยู่กับโปรแกรมที่กำลังสร้าง แต่อาจรวมถึงสิ่งต่อไปนี้:
- ไฟล์สำคัญในแอปพลิเคชัน เช่น ไฟล์ที่สร้างโดยทีมพัฒนา ฐานข้อมูลที่เข้าถึงในขณะที่โปรแกรมกำลังทำงาน และแอปพลิเคชันของบุคคลที่สาม
- ฟังก์ชันและรูทีนย่อย รวมถึงคำอธิบายเกี่ยวกับการใช้ฟังก์ชัน/รูทีนย่อย ค่าอินพุตและเอาต์พุต
- ตัวแปรโปรแกรมและค่าคงที่ และวิธีการใช้งาน
- โครงสร้างโปรแกรมโดยรวม สำหรับโปรแกรมที่ใช้ไดรฟ์ คุณอาจต้องอธิบายแต่ละโมดูลและไลบรารี หรือหากคุณกำลังเขียนคู่มือสำหรับโปรแกรมบนเว็บ คุณอาจต้องอธิบายว่าแต่ละหน้าใช้ไฟล์ใดบ้าง
ขั้นตอนที่ 2 ตัดสินใจว่าควรมีเอกสารในระดับใดและสามารถแยกออกจากรหัสโปรแกรมได้
ยิ่งมีเอกสารทางเทคนิครวมอยู่ในโค้ดโปรแกรมมากเท่าไร การอัปเดตและบำรุงรักษาก็จะยิ่งง่ายขึ้น เช่นเดียวกับการอธิบายเวอร์ชันต่างๆ ของโปรแกรม อย่างน้อยที่สุด เอกสารประกอบในโค้ดโปรแกรมควรรวมถึงการใช้ฟังก์ชัน รูทีนย่อย ตัวแปร และค่าคงที่
- หากซอร์สโค้ดของคุณยาว คุณสามารถเขียนเอกสารประกอบในไฟล์วิธีใช้ ซึ่งสามารถจัดทำดัชนีหรือค้นหาด้วยคีย์เวิร์ดบางคำได้ ไฟล์เอกสารแยกต่างหากจะมีประโยชน์หากตรรกะของโปรแกรมถูกแบ่งออกเป็นหลายหน้าและมีไฟล์สนับสนุน เช่น เว็บแอปพลิเคชัน
- ภาษาโปรแกรมบางภาษา (เช่น Java, Visual Basic. NET หรือ C#) มีมาตรฐานเอกสารรหัสของตนเอง ในกรณีดังกล่าว ให้ปฏิบัติตามเอกสารมาตรฐานที่ต้องรวมอยู่ในซอร์สโค้ด
ขั้นตอนที่ 3 เลือกเครื่องมือเอกสารที่เหมาะสม
ในบางกรณี เครื่องมือเอกสารจะถูกกำหนดโดยภาษาโปรแกรมที่ใช้ ภาษา C++, C#, Visual Basic, Java, PHP และอื่นๆ มีเครื่องมือเอกสารของตัวเอง อย่างไรก็ตาม หากไม่ เครื่องมือที่ใช้จะขึ้นอยู่กับเอกสารที่จำเป็น
- โปรแกรมประมวลผลคำ เช่น Microsoft Word เหมาะสำหรับการสร้างไฟล์ข้อความของเอกสาร ตราบใดที่เอกสารประกอบมีความกระชับและเรียบง่าย ในการสร้างเอกสารขนาดยาวที่มีข้อความที่ซับซ้อน ผู้เขียนด้านเทคนิคส่วนใหญ่เลือกเครื่องมือเอกสารเฉพาะทาง เช่น Adobe FrameMaker
- ไฟล์วิธีใช้สำหรับการจัดทำเอกสารซอร์สโค้ดสามารถสร้างได้ด้วยโปรแกรมสร้างไฟล์สนับสนุน เช่น RoboHelp, Help and Manual, Doc-To-Help, MadCap Flare หรือ HelpLogix
วิธีที่ 2 จาก 2: การเขียนเอกสารซอฟต์แวร์สำหรับผู้ใช้ปลายทาง
ขั้นตอนที่ 1 รู้เหตุผลทางธุรกิจที่เป็นรากฐานของการจัดทำคู่มือ
แม้ว่าเหตุผลหลักสำหรับเอกสารประกอบซอฟต์แวร์คือการช่วยให้ผู้ใช้เข้าใจวิธีใช้แอปพลิเคชัน แต่ก็มีสาเหตุอื่นๆ อีกหลายประการที่อาจรองรับการสร้างเอกสาร เช่น ช่วยฝ่ายการตลาดขายแอปพลิเคชัน ปรับปรุงภาพลักษณ์ของบริษัท และลดการสนับสนุนทางเทคนิค ค่าใช้จ่าย ในบางกรณี เอกสารจะต้องเป็นไปตามระเบียบข้อบังคับหรือข้อกำหนดทางกฎหมายอื่นๆ
อย่างไรก็ตาม เอกสารประกอบไม่สามารถทดแทนอินเทอร์เฟซได้ดี หากแอปพลิเคชันต้องการเอกสารจำนวนมากในการทำงาน แอปพลิเคชันนั้นควรได้รับการออกแบบให้ใช้งานง่ายขึ้น
ขั้นตอนที่ 2 รู้จักกลุ่มเป้าหมายของเอกสาร
โดยทั่วไป ผู้ใช้ซอฟต์แวร์มีความรู้เกี่ยวกับคอมพิวเตอร์ที่จำกัดนอกเหนือจากแอปพลิเคชันที่ตนใช้ มีหลายวิธีในการตอบสนองความต้องการด้านเอกสาร:
- ให้ความสนใจกับชื่อของผู้ใช้ซอฟต์แวร์ ตัวอย่างเช่น ผู้ดูแลระบบโดยทั่วไปเข้าใจโปรแกรมคอมพิวเตอร์ต่างๆ ในขณะที่เลขานุการรู้เพียงโปรแกรมที่เขาใช้ในการป้อนข้อมูล
- ให้ความสนใจกับผู้ใช้ซอฟต์แวร์ แม้ว่าโดยทั่วไปตำแหน่งของพวกเขาจะเข้ากันได้กับงานที่ทำ แต่ตำแหน่งเหล่านี้อาจมีปริมาณงานที่แตกต่างกัน ขึ้นอยู่กับสถานที่ประกอบธุรกิจ การสัมภาษณ์ผู้ที่มีแนวโน้มจะเป็นผู้ใช้ คุณจะทราบได้ว่าการประเมินตำแหน่งงานของพวกเขานั้นถูกต้องหรือไม่
- ให้ความสนใจกับเอกสารที่มีอยู่ เอกสารและข้อมูลจำเพาะเกี่ยวกับฟังก์ชันการทำงานของซอฟต์แวร์สามารถแสดงสิ่งที่ผู้ใช้จำเป็นต้องทราบเพื่อใช้งาน อย่างไรก็ตาม โปรดทราบว่าผู้ใช้อาจไม่ได้สนใจที่จะรู้จัก "อวัยวะภายใน" ของโปรแกรม
- รู้ว่าต้องใช้อะไรในการทำงานให้เสร็จ และต้องทำอะไรก่อนที่คุณจะทำงานให้เสร็จ
ขั้นตอนที่ 3 กำหนดรูปแบบที่เหมาะสมสำหรับเอกสาร
เอกสารประกอบซอฟต์แวร์สามารถจัดเรียงได้ 1 หรือ 2 รูปแบบ ได้แก่ หนังสืออ้างอิงและคู่มือ บางครั้งการรวมทั้งสองรูปแบบเข้าด้วยกันอาจเป็นทางออกที่ดี
- รูปแบบการอ้างอิงใช้เพื่ออธิบายคุณลักษณะของซอฟต์แวร์ทั้งหมด เช่น ปุ่ม แท็บ ฟิลด์ และกล่องโต้ตอบ และวิธีการทำงาน ไฟล์วิธีใช้บางไฟล์เขียนในรูปแบบนี้ โดยเฉพาะไฟล์ที่มีความละเอียดอ่อนต่อบริบท เมื่อผู้ใช้คลิกที่ Help ในหน้าจอใดหน้าจอหนึ่ง ผู้ใช้จะได้รับหัวข้อที่เกี่ยวข้อง
- รูปแบบคู่มือใช้เพื่ออธิบายวิธีดำเนินการบางอย่างกับซอฟต์แวร์ คู่มือมักจะอยู่ในรูปแบบการพิมพ์หรือ PDF แม้ว่าหน้าช่วยเหลือบางหน้าจะมีคำแนะนำเกี่ยวกับวิธีการทำบางสิ่งด้วย (โดยทั่วไป รูปแบบที่กำหนดด้วยตนเองไม่คำนึงถึงบริบท แต่อาจเชื่อมโยงจากหัวข้อที่มีความละเอียดอ่อนตามบริบท) โดยทั่วไปแล้ว คู่มือจะอยู่ในรูปของคู่มือ โดยมีบทสรุปของงานที่ต้องทำในคำอธิบายและคู่มือที่จัดรูปแบบเป็นขั้นตอน
ขั้นตอนที่ 4 ตัดสินใจเกี่ยวกับประเภทของเอกสาร
เอกสารประกอบซอฟต์แวร์สำหรับผู้ใช้อาจบรรจุอยู่ในรูปแบบใดรูปแบบหนึ่งดังต่อไปนี้: คู่มือฉบับพิมพ์ ไฟล์ PDF ไฟล์วิธีใช้ หรือความช่วยเหลือออนไลน์ เอกสารแต่ละประเภทได้รับการออกแบบเพื่อแสดงวิธีใช้ฟังก์ชันต่างๆ ของซอฟต์แวร์ ไม่ว่าจะเป็นคู่มือหรือบทช่วยสอน เอกสารและหน้าช่วยเหลือออนไลน์อาจรวมถึงวิดีโอสาธิต ข้อความ และภาพนิ่ง
ไฟล์วิธีใช้และสนับสนุนออนไลน์ควรจัดทำดัชนีและค้นหาได้โดยใช้คำสำคัญ เพื่อให้ผู้ใช้สามารถค้นหาข้อมูลที่ต้องการได้อย่างรวดเร็ว แม้ว่าแอปพลิเคชันตัวสร้างไฟล์วิธีใช้สามารถสร้างดัชนีได้โดยอัตโนมัติ แต่ก็ยังแนะนำให้คุณสร้างดัชนีด้วยตนเองโดยใช้คำสำคัญที่ค้นหาโดยทั่วไป
ขั้นตอนที่ 5. เลือกเครื่องมือเอกสารที่เหมาะสม
คุณสามารถสร้างคู่มือหรือ PDF ที่พิมพ์ด้วยโปรแกรมประมวลผลคำ เช่น Word หรือโปรแกรมแก้ไขข้อความขั้นสูง เช่น FrameMaker ขึ้นอยู่กับความยาวและความซับซ้อนของไฟล์ ไฟล์วิธีใช้สามารถเขียนได้ด้วยโปรแกรมสร้างไฟล์วิธีใช้ เช่น RoboHelp, Help and Manual, Doc-To-Help, Flare, HelpLogix หรือ HelpServer
เคล็ดลับ
- ข้อความของเอกสารประกอบโปรแกรมควรมีโครงสร้างในลักษณะที่อ่านง่าย วางรูปภาพให้ใกล้กับข้อความที่เหมาะสมที่สุด แบ่งเอกสารตามส่วนและหัวข้ออย่างมีเหตุผล แต่ละส่วนหรือหัวข้อควรอธิบายปัญหาเฉพาะ ทั้งคุณสมบัติของงานและโปรแกรม สามารถอธิบายปัญหาที่เกี่ยวข้องได้ด้วยลิงก์หรือรายการอ้างอิง
- เครื่องมือเอกสารแต่ละอย่างที่อธิบายไว้ในบทความนี้สามารถเสริมด้วยโปรแกรมสร้างภาพหน้าจอ เช่น SnagIt หากเอกสารของคุณต้องการภาพหน้าจอหลายภาพ เช่นเดียวกับเอกสารอื่นๆ คุณควรใส่ภาพหน้าจอเพื่อช่วยอธิบายวิธีการทำงานของแอป แทนที่จะ "ล่อ" ผู้ใช้
- การให้ความสำคัญกับสไตล์เป็นสิ่งสำคัญมาก โดยเฉพาะอย่างยิ่งหากคุณกำลังเขียนเอกสารซอฟต์แวร์สำหรับผู้ใช้ปลายทาง กล่าวถึงผู้ใช้ด้วยสรรพนาม "คุณ" แทน "ผู้ใช้"
