เราประเมินคุณภาพของเอกสารอย่างไร

สวัสดีฮับ! ฉันชื่อ Lesha เป็นนักวิเคราะห์ระบบให้กับทีมผลิตภัณฑ์ของ Alfa-Bank ตอนนี้ฉันกำลังพัฒนาธนาคารออนไลน์ใหม่สำหรับนิติบุคคลและผู้ประกอบการรายบุคคล

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

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

คุณภาพเอกสาร

เพื่อไม่ให้ข้อความ "New Internet Bank" ซ้ำหลายสิบครั้งฉันจะเขียน NIB ขณะนี้เรามีทีมงานมากกว่าสิบทีมที่ทำงานเกี่ยวกับการพัฒนา NIB สำหรับผู้ประกอบการและนิติบุคคล ยิ่งไปกว่านั้น แต่ละคนยังสร้างเอกสารของตนเองสำหรับบริการหรือเว็บแอปพลิเคชันใหม่ตั้งแต่เริ่มต้น หรือทำการเปลี่ยนแปลงกับบริการปัจจุบัน ด้วยแนวทางนี้ เอกสารโดยหลักการจะมีคุณภาพสูงได้หรือไม่

และเพื่อกำหนดคุณภาพของเอกสาร เราได้ระบุคุณลักษณะหลักสามประการ

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

สรุป - เอกสารครบถ้วน ทันสมัย ​​และเข้าใจง่าย

Опрос

เพื่อประเมินคุณภาพของเอกสาร เราตัดสินใจสัมภาษณ์ผู้ที่ทำงานโดยตรงกับเอกสารนั้น: นักวิเคราะห์ NIB ขอให้ผู้ตอบแบบสอบถามประเมินข้อความ 10 ข้อความตามโครงการ "ในระดับ 1 ถึง 5 (ไม่เห็นด้วยอย่างยิ่ง - เห็นด้วยอย่างยิ่ง)"

ข้อความดังกล่าวสะท้อนถึงลักษณะของเอกสารเชิงคุณภาพและความเห็นของผู้รวบรวมการสำรวจเกี่ยวกับเอกสาร NIB

1. เอกสารสำหรับแอปพลิเคชัน NIB เป็นข้อมูลล่าสุดและสอดคล้องกับการใช้งานอย่างสมบูรณ์
2. การใช้งานแอปพลิเคชัน NIB ได้รับการบันทึกไว้อย่างครบถ้วน
3. เอกสารสำหรับแอปพลิเคชัน NIB จำเป็นสำหรับการสนับสนุนการทำงานเท่านั้น
4. เอกสารประกอบการสมัคร NIB เป็นปัจจุบัน ณ เวลาที่ยื่นขอรับการสนับสนุนด้านการทำงาน
5. นักพัฒนาแอปพลิเคชัน NIB ใช้เอกสารประกอบเพื่อทำความเข้าใจสิ่งที่พวกเขาจำเป็นต้องนำไปใช้
6. มีเอกสารประกอบเพียงพอสำหรับแอปพลิเคชัน NIB เพื่อทำความเข้าใจวิธีการนำไปใช้
7. ฉันจะอัปเดตเอกสารเกี่ยวกับโครงการ NIB ทันทีหากได้รับการสรุปผล (โดยทีมของฉัน)
8. นักพัฒนาแอปพลิเคชัน NIB ตรวจสอบเอกสาร
9. ฉันมีความเข้าใจที่ชัดเจนเกี่ยวกับวิธีการเตรียมเอกสารสำหรับโครงการ NIB
10. ฉันเข้าใจว่าเมื่อใดควรเขียน/อัปเดตเอกสารสำหรับโครงการ NIB

เห็นได้ชัดว่าการตอบเพียง “ตั้งแต่ 1 ถึง 5” อาจไม่เปิดเผยรายละเอียดที่จำเป็น ดังนั้นบุคคลจึงสามารถแสดงความคิดเห็นในแต่ละรายการได้

เราทำทั้งหมดนี้ผ่าน Slack ขององค์กร - เราเพียงส่งคำเชิญไปยังนักวิเคราะห์ระบบเพื่อทำแบบสำรวจ มีนักวิเคราะห์ 15 คน (9 คนจากมอสโกวและ 6 คนจากเซนต์ปีเตอร์สเบิร์ก) หลังจากการสำรวจเสร็จสิ้น เราได้สร้างคะแนนเฉลี่ยสำหรับแต่ละข้อความจากทั้งหมด 10 ข้อความ ซึ่งต่อมาเรากำหนดเป็นมาตรฐาน

นี่คือสิ่งที่เกิดขึ้น

การสำรวจแสดงให้เห็นว่าแม้ว่านักวิเคราะห์มีแนวโน้มที่จะเชื่อว่าการใช้งานแอปพลิเคชัน NIB ได้รับการบันทึกไว้อย่างครบถ้วน แต่ก็ไม่ได้ให้ข้อตกลงที่ชัดเจน (0.2) ตามตัวอย่างที่เฉพาะเจาะจง พวกเขาชี้ให้เห็นว่าฐานข้อมูลและคิวจำนวนหนึ่งจากโซลูชันที่มีอยู่ไม่ครอบคลุมอยู่ในเอกสารประกอบ นักพัฒนาซอฟต์แวร์สามารถบอกนักวิเคราะห์ได้ว่าไม่ใช่ทุกอย่างที่ได้รับการบันทึกไว้ แต่วิทยานิพนธ์ที่นักพัฒนาตรวจสอบเอกสารยังไม่ได้รับการสนับสนุนที่ชัดเจน (0.33) นั่นคือความเสี่ยงในการอธิบายวิธีแก้ปัญหาที่นำไปใช้ไม่ครบถ้วนยังคงอยู่

ความเกี่ยวข้องง่ายขึ้น - แม้ว่าจะไม่มีข้อตกลงที่ชัดเจนอีกต่อไป (0,13) แต่นักวิเคราะห์ยังคงมีแนวโน้มที่จะพิจารณาเอกสารที่เกี่ยวข้อง ความคิดเห็นช่วยให้เราเข้าใจว่าปัญหาที่เกี่ยวข้องกับความเกี่ยวข้องมักเกิดขึ้นที่ด้านหน้ามากกว่าตรงกลาง อย่างไรก็ตาม พวกเขาไม่ได้เขียนถึงเราเกี่ยวกับการสนับสนุนเลย

ในส่วนที่ว่านักวิเคราะห์เข้าใจหรือไม่ว่าเมื่อจำเป็นต้องเขียนและอัปเดตเอกสาร ข้อตกลงมีความเหมือนกันมากกว่ามาก (1,33) รวมถึงการออกแบบ (1.07) สิ่งที่สังเกตเห็นว่าเป็นความไม่สะดวกคือการไม่มีกฎเกณฑ์เดียวกันในการดูแลเอกสาร ดังนั้น เพื่อไม่ให้เปิดโหมด "ใครเข้าป่า ใครได้ฟืน" พวกเขาจะต้องทำงานตามตัวอย่างเอกสารที่มีอยู่ ดังนั้นความปรารถนาที่เป็นประโยชน์คือการสร้างมาตรฐานสำหรับการจัดการเอกสารและพัฒนาเทมเพลตสำหรับส่วนต่างๆ

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

แต่สิ่งที่ผู้ตอบแบบสอบถามไม่เห็นด้วย (ค่อนข้างเป็นเอกฉันท์) ก็คือเอกสารสำหรับแอปพลิเคชัน NIB โดยหลักการแล้ว จำเป็นสำหรับการสนับสนุนการทำงานเท่านั้น (-1.53) นักวิเคราะห์ถูกกล่าวถึงบ่อยที่สุดว่าเป็นผู้บริโภคเอกสาร ส่วนที่เหลือของทีม (นักพัฒนา) - น้อยกว่ามาก นอกจากนี้ นักวิเคราะห์เชื่อว่านักพัฒนาไม่ได้ใช้เอกสารประกอบเพื่อทำความเข้าใจสิ่งที่พวกเขาจำเป็นต้องนำไปใช้ แม้ว่าจะไม่ได้มีมติเป็นเอกฉันท์ก็ตาม (-0.06) สิ่งนี้คาดว่าจะเกิดขึ้นภายใต้เงื่อนไขที่การพัฒนาโค้ดและการเขียนเอกสารดำเนินการไปพร้อมๆ กัน

สิ่งสำคัญที่สุดคืออะไร และเหตุใดเราจึงต้องมีตัวเลขเหล่านี้

เพื่อปรับปรุงคุณภาพของเอกสาร เราตัดสินใจดำเนินการดังต่อไปนี้:

1. ขอให้นักพัฒนาตรวจสอบเอกสารที่เป็นลายลักษณ์อักษร
2. หากเป็นไปได้ ให้อัปเดตเอกสารให้ทันเวลา โดยเริ่มจากด้านหน้าก่อน
3. สร้างและปรับใช้มาตรฐานสำหรับการจัดทำเอกสารโครงการ NIB เพื่อให้ทุกคนสามารถเข้าใจได้อย่างรวดเร็วว่าองค์ประกอบระบบใดและควรอธิบายอย่างไรอย่างชัดเจน พัฒนาเทมเพลตที่เหมาะสม

ทั้งหมดนี้น่าจะช่วยยกระดับคุณภาพของเอกสารขึ้นไปอีกระดับหนึ่ง

อย่างน้อยฉันก็หวังเช่นนั้น

ที่มา: will.com