เอกสารสำหรับผู้ใช้: สาเหตุที่ทำให้เสียและวิธีแก้ไข

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

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

ปัญหาที่ 1: บทความที่ไม่ชัดเจนและเขียนไม่ดี

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

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

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

ปัญหาที่ 2. บทความไม่ได้ตอบทุกคำถาม

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

เอกสารไม่ตามการพัฒนา

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

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

เอกสารประกอบไม่สะท้อนถึงคำขอของผู้ใช้

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

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

เอกสารไม่ได้รับการปรับปรุง

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

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

ปัญหาที่ 3. ใช้เวลานานในการค้นหาบทความที่ถูกต้อง

บทความที่ไม่พบก็ไม่ดีกว่าบทความที่ไม่พบ คำขวัญของเอกสารที่ดีควรเป็น “ค้นหาง่าย ค้นหาง่าย” จะบรรลุเป้าหมายนี้ได้อย่างไร?

จัดโครงสร้างและกำหนดหลักการเลือกหัวข้อ. โครงสร้างควรโปร่งใสที่สุดเท่าที่จะเป็นไปได้ เพื่อที่ผู้อ่านจะได้ไม่คิดว่า “ฉันจะหาบทความนี้ได้ที่ไหน” โดยสรุป มีสองวิธี: จากอินเทอร์เฟซและจากงาน

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

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

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

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

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

ทางด้านขวาในหน้าต่างป๊อปอัปคือลิงก์ไปยังบทความเกี่ยวกับการตั้งค่า DNSSEC ในส่วนการจัดการโดเมนของ ISPmanager

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

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

ปัญหาที่ 4 รูปแบบที่ล้าสมัยรบกวนการรับรู้

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

มีภาพหน้าจอและไฮไลท์มากมายในบทความนี้ซึ่งไม่ได้ช่วย แต่รบกวนการรับรู้เท่านั้น (สามารถคลิกรูปภาพได้)

คุณไม่ควรอ่านเอกสารประกอบที่มีเอฟเฟกต์มากมาย แต่คุณต้องคำนึงถึงกฎพื้นฐานด้วย

เค้าโครง. กำหนดความกว้าง แบบอักษร ขนาด ส่วนหัว และช่องว่างภายในของข้อความเนื้อหา จ้างนักออกแบบและยอมรับงานหรือทำเอง อ่านหนังสือของ Artyom Gorbunov เรื่อง “Typography and Layout” นำเสนอเพียงมุมมองเดียวของเค้าโครง แต่ก็ค่อนข้างเพียงพอ

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

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

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

รูปแบบ. รวมหลายรูปแบบในบทความของคุณ: ข้อความ วิดีโอ และรูปภาพ สิ่งนี้จะปรับปรุงการรับรู้

อย่าพยายามปกปิดปัญหาด้วยการจัดวางที่สวยงาม จริงๆ แล้วเราเองก็หวังว่า "กระดาษห่อ" จะบันทึกเอกสารที่ล้าสมัย - มันไม่ได้ผล ข้อความมีเสียงรบกวนและรายละเอียดที่ไม่จำเป็นมากจนทำให้กฎระเบียบและการออกแบบใหม่ไม่มีอำนาจ

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

จะเริ่มปรับปรุงได้ที่ไหนและจะอยู่รอดได้อย่างไร

หากเอกสารของคุณมีขนาดใหญ่เท่ากับ ISPsystem และคุณไม่รู้ว่าจะเริ่มต้นอย่างไร ให้เริ่มจากปัญหาที่ใหญ่ที่สุด ลูกค้าไม่เข้าใจเอกสาร - ปรับปรุงข้อความ, จัดทำกฎระเบียบ, ฝึกอบรมนักเขียน เอกสารล้าสมัย - ดูแลกระบวนการภายใน เริ่มต้นด้วยบทความยอดนิยมเกี่ยวกับผลิตภัณฑ์ยอดนิยม: ถามฝ่ายสนับสนุน ดูการวิเคราะห์ไซต์ และข้อความค้นหาในเครื่องมือค้นหา

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

ที่มา: will.com