แนวทางที่มุ่งเน้นการตัดสินใจ ไม่ใช่งาน

 (technicalwriting.dev)
3 คะแนน โดย GN⁺ 2024-10-20 | 1 ความคิดเห็น | แชร์ทาง WhatsApp

  • มุ่งเน้นไปที่การตัดสินใจ

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

สรุปโดย GN⁺

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

บทความที่เกี่ยวข้อง

1 ความคิดเห็น

 
GN⁺ 2024-10-20
ความคิดเห็นจาก Hacker News

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

    • เกี่ยวกับย่อหน้าสุดท้าย เว็บไซต์ UK gov ทำเรื่องนี้ได้ดีมาก มีหน้า landing page ที่อธิบายขั้นตอน และหลังจากมีคำเตือนกับข้อควรระวังแล้วจึงจะไปกรอกแบบฟอร์มจริงได้
      ถ้ากด “Start Now” จากผลลัพธ์ Google สำหรับการต่ออายุใบขับขี่ที่ https://www.gov.uk/renew-driving-licence ก็จะเข้าใจว่าหมายถึงอะไร
      ในมุมของ “power user” บางครั้งอาจรู้สึกเหมือนเป็นสิ่งรบกวน แต่ก็เข้าใจว่าต้องคำนึงถึงทุกคน
    • ความคิดเห็นนี้ทำให้นึกว่าคุณน่าจะชอบ Every Page Is Page One แก่นคือผู้คนอาจเข้ามายังหน้าใดก็ได้ในไซต์เอกสาร ดังนั้นทุกหน้าจึงควรให้บริบทได้อย่างรวดเร็ว และช่วยให้ผู้ใช้ตัดสินได้ง่ายว่าตนอยู่บนเส้นทางที่ถูกต้องหรือไม่
      ชื่อหนังสือก็มาจากแนวคิดนี้ หน้าใดก็ตามในไซต์อาจเป็นหน้าแรกสำหรับผู้ใช้ได้
    • อยากให้ เอกสารทางเทคนิค มีแนวทางแบบนี้มากขึ้น ผมเป็นคนที่มักสงสัยอยู่เรื่อยว่าทำไมจึงทำด้วยวิธีใดวิธีหนึ่ง เลยมักหลุดออกไปตามประเด็นข้างเคียงจนช้าลง

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

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

  • ดีมากจริง ๆ สั้น ตรงประเด็น และมี insight ผมมีวิธีคิดที่ใกล้กับการมอง ภาพใหญ่ ดังนั้นไม่ใช่แค่ว่าวิธีทำบางอย่างเป็นอย่างไร แต่ทำไมจึงเป็นเช่นนั้น และเชื่อมโยงกับบริบทที่ใหญ่กว่าอย่างไรก็สำคัญด้วย
    ผมแนะนำให้นักพัฒนาใช้ฟิลด์ Description ของ Jira story และ task อย่างจริงจัง เพื่อใส่ภาพรวมว่าเราทำงานนี้ไปทำไม และเชื่อมกับภาพใหญ่ได้อย่างไร บางคนดูเหมือนจะไม่ชอบ แต่บางคนก็ค่อนข้างชอบ
    ผมชอบเพราะได้ให้ภาพใหญ่ของโปรเจกต์ ส่วนเหล่านักพัฒนาก็พอใจเพราะการเข้าใจภาพใหญ่นั้นช่วยให้ทำงานได้อย่างเป็นอิสระมากขึ้น

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

    • น่าสนใจที่ความคิดแรกไม่ใช่ “ฉันจะใช้สิ่งนี้ปรับปรุงเอกสารที่ฉันเขียนได้อย่างไร” แต่เป็น “ฉันจะพิสูจน์ได้อย่างไรว่าสิ่งนี้ปรับปรุงเอกสารที่ฉันเขียน” ดูเหมือนคุณทำงานอยู่ในสภาพแวดล้อมที่ค่อนข้างเข้มงวด
    • ในที่ที่เรามีอิสระจะทำสิ่งที่คิดว่าดีที่สุดเพื่อผู้ใช้ได้ เช่น โปรเจกต์ส่วนตัว มีโอกาสสูงที่จะใช้ การสนับสนุนการตัดสินใจ เป็นฐานของกลยุทธ์เอกสาร
      จากมุมมองของการทำงานอย่างมีความรับผิดชอบ ถ้าผมรู้สึกว่า “การสนับสนุนการตัดสินใจ” คือสิ่งที่ดีที่สุดสำหรับโปรเจกต์ของผม ก็ดูเหมือนว่าผมมีหน้าที่ต้องนำกลยุทธ์นี้ไปใช้กับเอกสารงานด้วย
      โชคดีที่ไม่ได้มีผู้จัดการสายตาสั้นมาบีบคออยู่ แต่ถ้าต้องโน้มน้าวในที่ทำงาน ผมคงทำแบบนี้ ก่อนอื่นอธิบายตรรกะของกลยุทธ์ การสนับสนุนการตัดสินใจสมเหตุสมผลและโน้มน้าวได้ เรายังเขียนเอกสารงานอยู่ แต่ “งาน” เป็นเพียง subset ของการสนับสนุนการตัดสินใจเท่านั้น
      จากนั้นนำเสนอตัวอย่างยาว ๆ จาก support ticket, การถกกันในห้องแชต ฯลฯ ที่ปัญหาคือขาดการสนับสนุนการตัดสินใจ เพื่อความซื่อสัตย์ทางปัญญา ให้แสดงรายการ support ticket ที่เกี่ยวกับเอกสารทั้งหมด พร้อม subset ที่เกี่ยวกับการสนับสนุนการตัดสินใจด้วย ถ้าสัดส่วนมากพอจนมองข้ามไม่ได้ เช่น 25% ก็ควรมอง “การสนับสนุนการตัดสินใจ” ให้ลึกขึ้น
      สุดท้าย ผู้มีส่วนได้ส่วนเสียอาจยกตัวอย่างจากงานของตนเองได้ เช่น “จำได้ไหมว่าตอนต้องตัดสินใจว่าจะเปลี่ยนไปใช้ CMS อะไร มันยากมากแค่ไหน?”

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

    • Thinking in Bets เป็นหนึ่งในหนังสือที่มีประโยชน์ที่สุดต่อวิธีที่ผมใช้เข้าหา software engineering มันไม่ใช่หนังสือเกี่ยวกับโค้ด แต่เป็นหนังสือเกี่ยวกับวิธีตัดสินใจอย่างมีประสิทธิภาพในสภาพแวดล้อมที่มีข้อมูลจำกัด
    • ไม่ค่อยเข้าใจว่าการเข้าหางานด้วยวิธีแบบ fuzzy logic หมายถึงอะไร ช่วยอธิบายเพิ่มอีกหน่อยได้ไหม?

  • แนวทางที่ดีในการตัดสินใจในบริบทของทีม Rich Hickey อธิบายไว้ที่นี่: https://www.youtube.com/watch?v=c5QF2HjHLSE
    ชื่อทอล์กคือ “Design in Practice” แต่เนื้อหาจริง ๆ ว่าด้วย การตัดสินใจ

  • “งานคือทุกสิ่งที่ต้องทำเพื่อไปจากการตัดสินใจหนึ่งสู่การตัดสินใจถัดไปเท่านั้น” — Venkatesh Rao, Tempo

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

  • คำแนะนำนี้ทำให้สับสนนิดหน่อย เป็นการตัดสินใจของใคร? ของ ผู้สร้างเครื่องมือ หรือของผู้ใช้?
    โดยทั่วไปแล้วดูเหมือนเป็นการทำให้ง่ายเกินไป สิ่งที่มีประโยชน์กว่าคือการเข้าใจก่อนว่าเอกสารที่กำลังเขียนเป็นประเภทไหน ระหว่างเอกสารเพื่อการเรียนรู้, แบบมุ่งเป้าหมาย, เพื่อความเข้าใจ หรือเพื่อให้ข้อมูล [1]
    เช่น ถ้ากำลังค้นหา API ของฟังก์ชันหนึ่ง แล้วมีข้อมูล “การตัดสินใจ” ถาโถมเข้ามา ก็อาจทำให้น่ารำคาญได้
    1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

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

  • การรู้ว่าผู้คนใช้ระบบของผม/ฉันอย่างไรเพื่อตัดสินใจนั้นสำคัญ ผม/ฉันเห็นว่าความรู้นั้นจำเป็นต่อการดูแลรักษา ขยาย หรือสร้างระบบใหม่
    แต่บทความนี้เสนอความรับผิดชอบที่สูงกว่านั้น คือควรบันทึก กระบวนการตัดสินใจ ของผู้ใช้ และบอกบริบท ตัวเลือก รวมถึงผลลัพธ์ของการตัดสินใจ
    ผม/ฉันเคยทำงานกับ “ระบบสนับสนุนการตัดสินใจ” ที่มีความรับผิดชอบแบบนั้น และมันซับซ้อนขึ้นอย่างรวดเร็วมาก ผู้คนชอบถกเถียงกันเรื่องผลลัพธ์ แม้จะรู้ผลลัพธ์นั้นแน่ชัด 100% แล้วก็ตาม พวกเขาไม่ชอบอีเมลอัตโนมัติที่มีความไม่แน่นอน และก็ไม่ชอบที่เอกสารบังคับให้เลือกแบบสองทาง ทั้งที่ในความเป็นจริงมีตัวเลือกมากกว่านั้นมาก
    นอกเหนือจากบทความนี้แล้ว ในหนังสือผม/ฉันอยากให้พูดถึงแนวคิดเรื่อง การควบคุม ด้วย ถ้าจะบันทึกพฤติกรรมบางอย่างไว้ในเอกสาร เอกสารควรมีการรับประกันหรือการบังคับใช้ต่อพฤติกรรมนั้นในระดับหนึ่ง เพื่อให้ยังคงมีอำนาจน่าเชื่อถือได้ ส่วนตัวแล้วผม/ฉันมองว่าการขาดทั้งอำนาจและการควบคุมเป็นจุดบอดที่พบได้บ่อยและสำคัญของแนวริเริ่มด้านการเขียนอย่าง https://www.plainlanguage.gov

    • ขออ้างสิ่งที่เคยเขียนเกี่ยวกับบทความนี้ใน r/technicalwriting อีกครั้ง สิ่งที่สำคัญจริง ๆ ในแนวคิดของ Baker คือหลักคำสอนของการศึกษาด้านเอกสารเทคนิคนั้นปรับเข้าหาแนวคิดที่ยึดงานเป็นศูนย์กลางอย่างเด็ดขาด
      ถ้าสำรวจนักเขียนเอกสารเทคนิคมืออาชีพ คนส่วนใหญ่น่าจะเชื่อว่า “การช่วยให้ผู้ใช้ทำงานสำเร็จ” คือเป้าหมายหลักของเอกสาร หรืออาจเป็นเป้าหมายหลักที่สุดเลยก็ได้
      คำอ้างสั้น ๆ ของ Baker ค่อนข้าง radical ในความหมายภาษาละตินว่า “กลับไปสู่ราก” เพราะมันเสนอว่าสมมติฐานพื้นฐานข้อหนึ่งของเราขาดตกบกพร่องอย่างมาก
      ส่วนตัวแล้ว เหตุผลที่แนวคิดของ Baker น่าสนใจคือมันตั้งมาตรฐานไว้สูงกว่ามาตรฐานที่คาดหวังจากเอกสารเทคนิคในปัจจุบันมาก เอกสารจำนวนมากถือว่าเมื่อบันทึกงานไว้แล้วก็ “ภารกิจเสร็จสิ้น” แต่ Baker ดูเหมือนจะบอกว่าแค่นั้นยังไม่พอ
      แน่นอนว่ายังต้องบันทึกงานไว้ในเอกสารอยู่ แต่ตัวงานเป็นเพียงส่วนย่อยของข้อมูลที่ประกอบกันเป็นการตัดสินใจ
      ผม/ฉันจำไม่ได้ว่าหนังสือของ Baker ได้พูดถึงการควบคุมในแบบที่กล่าวไว้ตรงนี้หรือไม่ สำหรับผม/ฉันนี่เป็นแนวคิดใหม่ ขอบคุณมาก
      ตัวอย่างการควบคุมที่นึกออกอย่างเป็นรูปธรรมคือ เอกสารของผม/ฉันจำนวนไม่น้อยพึ่งพาหน้าของโปรเจกต์โอเพนซอร์สอื่น ถ้าหน้าภายนอกเหล่านั้นมีคุณภาพต่ำ ก็มีความเป็นไปได้สูงว่าการปรับปรุงเอกสารเหล่านั้นควรเป็นความรับผิดชอบของผม/ฉันด้วย หลายคนอาจมองว่าเอกสารที่อยู่นอกไซต์ของตัวเองอยู่นอกความรับผิดชอบของตัวเอง แต่ถ้าตั้งใจจะสนับสนุนการตัดสินใจจริง ๆ ใครเป็นผู้โฮสต์เอกสารนั้นก็ไม่สำคัญ
      บางทีเราอาจเรียนรู้อะไรได้มากจากทัศนคติของการเป็นพลเมืองโอเพนซอร์สที่ดี