กลุ่มเป้าหมาย
ฉันคิดว่าเมื่อตอบคำถามนี้คุณต้องถามว่าใครตั้งใจอ่านเอกสารนี้ นักพัฒนามีความต้องการที่แตกต่างอย่างสิ้นเชิงต่อผู้ใช้หรือแม้แต่นักวิเคราะห์ธุรกิจ
- ในฐานะนักพัฒนา: เอกสารที่เกี่ยวข้องกับรหัสที่กำลังศึกษารายละเอียดเช่นสัญญาส่วนต่อประสานและตัวอย่างการใช้งาน อาจมีเอกสารระดับสูงและรายละเอียดโปรโตคอลสำหรับการวัดที่ดี
- ในฐานะผู้ใช้: เอกสารพร้อมใช้งานผ่านเมนูวิธีใช้หรือเว็บไซต์ที่เข้าถึงได้เกี่ยวกับวิธีใช้ซอฟต์แวร์
- ในฐานะนักวิเคราะห์ธุรกิจ: เอกสารที่มีให้เป็นเอกสารหรือเป็นเว็บไซต์ที่เข้าถึงได้นั้นมีประโยชน์ รายละเอียดจำนวนเล็กน้อยเกี่ยวกับโปรโตคอลสถาปัตยกรรมระดับสูงและกรณีการใช้งานที่ดีที่สุด
ซ่อมบำรุง
แหล่งที่มาของเอกสารนี้จะขึ้นอยู่กับผู้ชมของคุณและใครเป็นผู้เขียนให้กับผู้ชมของคุณ
- มีเพียงบ้านนักพัฒนาหรือไม่? วางทุกอย่างไว้ในรหัส มันจะสนับสนุนให้มีการปรับปรุง คุณจะต้องทำงานในวัฒนธรรมที่ส่งเสริมการปรับปรุงเอกสารให้มีความสำคัญเท่ากับการเปลี่ยนแปลงรหัส
- มีบ้านของนักพัฒนาและนักเขียนเอกสารหรือไม่? แบ่งความรับผิดชอบ ใช้เครื่องมือที่มุ่งเน้นนักพัฒนาสำหรับนักพัฒนาใช้เครื่องมือตัวเขียนเอกสารสำหรับนักเขียนเอกสาร
หากเป็นไปได้ให้แน่ใจว่าตัวอย่างรหัสหรือกรณีการใช้สามารถดำเนินการได้ ทำการดำเนินการอัตโนมัติและตั้งค่าสถานะความล้มเหลวภายใน โอกาสที่หน้าเอกสารเหล่านี้ไม่ดีหรือไม่ดี
นอกจากนี้เครื่องมือใดก็ตามที่คุณเลือกที่จะเขียนเอกสารของคุณคุณต้องมีวิธีการที่เชื่อถือได้ในการเชื่อมโยงเอกสารเฉพาะรุ่นกับรหัสเฉพาะรุ่น สิ่งนี้ยังคงเป็นประโยชน์แม้ในดินแดนคลาวด์ที่มีความสุขด้วยการปรับใช้เพียงครั้งเดียว
การรวมเอกสาร
การรวมอาจจำเป็นต้องใช้ในการผลิตเอกสารบางอย่าง แต่โปรดทราบว่ามีเพียงผู้ใช้ที่คาดหวังที่เดียวในการเข้าถึงเอกสารทั้งหมดที่พวกเขาต้องการ
นักวิเคราะห์ธุรกิจมีความสุขมากกับข้อมูลจำเพาะ API, รายละเอียดการออกแบบและการใช้งานที่จะอยู่ในเอกสารแยกต่างหากหรือแยกส่วนของเว็บไซต์
นักพัฒนาต้องการทุกอย่างที่มองเห็นได้จากแหล่งที่มา แต่ก็ยินดีที่จะมีเอกสารการออกแบบระดับสูงสองสามฉบับและเอกสารข้อกำหนดรายละเอียดโปรโตคอลโดยละเอียดภายนอกรหัสแม้ว่าโดยเฉพาะอย่างยิ่งในเช็คเอาต์เดียวกัน
กรณีของคุณ
ความซื่อสัตย์เอกสารในวิกิของคุณอาจไม่ใช่เอกสารประเภทเดียวกันในรหัสฐานของคุณ มันอาจไม่สมเหตุสมผลที่จะรวมเข้าด้วยกัน
ในอีกทางหนึ่งการบูรณาการทั้งสองสามารถทำได้ด้วยวิธีง่าย ๆ
- เครื่องมือเอกสารต้นฉบับ (เช่น doxygen) สามารถสร้าง html และ wiki อาศัยอยู่บนเว็บเซิร์ฟเวอร์ มันจะเป็นจุดรวมง่าย ๆ เพียงแค่ให้บริการรุ่นที่สร้างขึ้นข้างวิกิและเชื่อมโยงระหว่างทั้งสอง
- ผลิตภัณฑ์ wiki บางตัวจะอนุญาตให้คุณเรียกใช้ wiki โดยตรงจากไฟล์ที่คุณสามารถเช็คอินไปยังรหัสฐาน สิ่งนี้จะทำให้เครื่องมือ wysiwyg ง่าย ๆ ในขณะที่รักษาเอกสารที่จับคู่กับรหัส
- รูปแบบอื่น ๆ เช่น PDF สามารถรองรับได้เช่นกัน แต่สิ่งนี้จะลงไปในเครื่องมือเฉพาะที่คุณต้องการใช้ มันอาจเหมาะสมที่จะขูดวิกิของคุณเป็นไฟล์มาร์กอัปและฟีดที่ผ่าน doxygen (หรือเครื่องมืออื่น ๆ ) มันอาจจะเหมาะสมที่จะ pdf wiki และแหล่งข้อมูลแยกจากกันและใช้เครื่องมือผสาน PDF
ในตอนท้ายของวันให้หาว่าระบบเอกสารใดที่มีค่าบำรุงรักษาต่ำและช่วยคุณในการส่งมอบผลิตภัณฑ์ที่มีคุณภาพสูงตามที่ผู้ชมผู้พัฒนานักวิเคราะห์ธุรกิจและผู้ใช้ของคุณเห็น อะไรก็ตามที่ขัดขวางกลุ่มใด ๆ เหล่านี้จำเป็นต้องลดคุณภาพของผลิตภัณฑ์