'เอกสาร' ประกอบด้วยอะไรบ้าง?

เมื่อเราพูดว่า 'เอกสาร' สำหรับผลิตภัณฑ์ซอฟต์แวร์สิ่งที่รวมอยู่และสิ่งที่ไม่ควรมี

ตัวอย่างเช่นคำถามล่าสุดถามว่าความคิดเห็นได้รับการพิจารณาเป็นเอกสารประกอบหรือไม่

แต่มีหลายพื้นที่อื่น ๆ ที่เป็นคำถามที่ถูกต้องเช่นกันบางอย่างชัดเจนกว่าคนอื่น:

• คู่มือ (ชัด)
• บันทึกประจำรุ่น
• สอน
• ความคิดเห็น
• คนอื่น ๆ ?

วาดเส้นตรงไหน ตัวอย่างเช่นหากเอกสารประกอบ 'กวดวิชา' เป็นเอกสาร 'วิดีโอสอน' หรือเป็นอย่างอื่น

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

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

_{ผู้ชม: นักพัฒนาซอฟต์แวร์โดยใช้ฐานข้อมูลของเราภาษาการเขียนโปรแกรมและเครื่องมือที่เกี่ยวข้อง (เช่นผู้ดูแลระบบลูกค้าเพื่อบอกว่า DB)}

เป้าหมายของเอกสารคือการอธิบายและอธิบายผลิตภัณฑ์ซอฟต์แวร์ดังนั้นคุณสามารถกำหนดเอกสารเป็นชุดของสิ่งประดิษฐ์ที่นำไปสู่คำอธิบายหรือคำอธิบายนั้น ๆ คุณอาจไม่ได้พิจารณาการกระทำที่เกี่ยวข้องเป็นส่วนหนึ่งของเอกสารประกอบ: เช่นหลักสูตรฝึกอบรมสัปดาห์ยาวไม่ใช่เอกสาร แต่เอกสารประกอบหลักสูตร การแชทไวท์บอร์ดห้านาทีไม่ใช่เอกสาร แต่รูปภาพของไวท์บอร์ดคือ

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

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

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

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

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

ปัจจัยบางอย่างที่จะเข้ามาเล่น:

• คุณกำลังพัฒนาซอฟแวร์ v1.0 และพวกมันกำลังเคลื่อนไปสู่โครงการอื่น ๆ หรือเป็นโครงการระยะยาวหรือไม่? ความคิดเห็น / เอกสารการออกแบบมีความสำคัญมากกว่าในกรณีหลัง ในทางตรงกันข้ามถ้าลูกค้าของคุณเป็นร้านโดนัท mom-and-pop และคุณกำลังเขียนเว็บไซต์สำหรับพวกเขาที่คุณจะไม่เคยเห็น ... ดีฉันเดาว่ารหัสเอกสารนั้นดี แต่ไม่สำคัญ
• คุณพัฒนาเกมมือถือหรือซอฟต์แวร์ที่ใช้ควบคุมอัตราการเต้นของหัวใจในโรงพยาบาลหรือไม่ เดาว่าอันไหนจะมีคำจำกัดความของ "ทำ" ที่มีเอกสารมากกว่านี้?
• ลูกค้าของคุณเป็นผู้ใช้ทั่วไปหรือเป็นผู้พัฒนารายอื่นหรือไม่ คุณมี API / SDK ที่คุณเปิดเผยหรือไม่?
• ระดับความเชี่ยวชาญของลูกค้าของคุณคืออะไร? สิ่งนี้มีผลต่อการเลือกวิดีโอการสอนและเนื้อหาที่เขียนเทียบกับแอพแบบฝึกหัดแบบโต้ตอบบางประเภท
• ลูกค้าของคุณใส่ใจกับสิ่งที่เปลี่ยนไปจากรุ่นเป็นรุ่นหรือไม่ บางคนทำ ส่วนใหญ่ทำไม่ได้ สำหรับบางคนมันเป็นกฎหมาย (หรือใกล้เคียงกับ) ที่จะดูแล

เอกสารเป็นสิ่งที่ตั้งใจอ่านโดยไม่ต้องดัดแปลง

ฉันคิดว่าคุณไม่ผิดไปกับคำนิยามตามจุดประสงค์ ... แต่ถ้าคุณกำหนดวัตถุประสงค์อย่างเหมาะสม

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

สำหรับ'ตัวอย่าง' ที่คุณจะให้ความแตกต่างแบบอ่านและไม่ดัดแปลงอาจกลายเป็นเรื่องสำคัญ

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

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

อะไรก็ตามที่ตอบคำถาม "ฉันจะทำอย่างไร ... " คือเอกสารประกอบ

สำหรับนักพัฒนาที่รายละเอียดความต้องการหมายถึง ( "ฉันจะรู้ว่าสิ่งที่จะเขียน") เอกสารการออกแบบ ( "ฉันจะอยู่ที่ความต้องการของฉัน"), การฝึกอบรมตรวจสอบย้อนกลับ ( "ฉันจะรู้ว่าที่อยู่การออกแบบของฉันทุกความต้องการของฉัน") แผนการทดสอบ ( "ฉันจะรู้งานรหัสของฉัน"), การทดสอบหน่วย ( "ฉันรู้ว่าฉันได้ safisfied ต้องการ X"), ความเห็นแบบอินไลน์ ( "ฉันจะทำให้แน่ใจว่า schlub ยากจนต่อไปเข้าใจว่าทำไมฉันเขียนมันนี้วิธี ") คำแนะนำในการปรับใช้ (" ฉันจะทำแพคเกจผลิตภัณฑ์นี้เพื่อการติดตั้ง ") ได้อย่างไร ฯลฯ

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