A Primer on เขียนเอกสารที่ดี

โพสต์นี้สนับสนุนโดยผู้เขียนรับเชิญ Jeff Matson เจฟฟ์เป็นหัวหน้าฝ่ายเอกสารสำหรับ GravityForms เขาเป็นผู้สร้างปลั๊กอิน Heartbeat Control WordPress และเป็นแฟนตัวยงของยุค 90

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

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

เอกสารที่ดีมีมากกว่าคำพูด

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

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

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

เอกสารมีผลกระทบมากกว่าที่คุณคิด

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

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

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

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

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

คุณจะเขียนเอกสารที่ดีขึ้นได้อย่างไร?

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

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

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

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

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

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

ศิลปะแห่งการเขียนเอกสารที่ดีกว่า

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

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

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

สิ่งที่เราได้เรียนรู้

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

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

เอกสารเร็ว เอกสารบ่อย ผลิตภัณฑ์ที่ยอดเยี่ยมเป็นมากกว่าโค้ดที่ยอดเยี่ยม แต่ยังมีการจัดทำเอกสารอย่างสวยงามอีกด้วย