Cách tiếp cận tập trung vào quyết định thay vì tác vụ

 (technicalwriting.dev)
3 điểm bởi GN⁺ 2024-10-20 | 1 bình luận | Chia sẻ qua WhatsApp

  • Tập trung vào quyết định

    • Trích dẫn từ Every Page Is Page One đã tạo ra một thay đổi lớn trong cách tiếp cận viết tài liệu kỹ thuật
    • Trong giao tiếp kỹ thuật, người ta chủ yếu nói về việc hỗ trợ tác vụ, nhưng trong nhiều trường hợp, thông tin mọi người cần để hoàn thành công việc không phải là cách máy móc vận hành mà là thông tin hỗ trợ ra quyết định
    • Chỉ tài liệu hóa quy trình thôi là chưa đủ
    • Cần cho người dùng biết họ phải đưa ra những quyết định nào, kết quả của các quyết định đó là gì, và dẫn họ đến các nguồn tài nguyên, tài liệu tham khảo có thể hỗ trợ việc ra quyết định càng nhiều càng tốt

Tóm tắt của GN⁺

  • Bài viết này nhấn mạnh tầm quan trọng của việc hỗ trợ ra quyết định trong viết tài liệu kỹ thuật
  • Cần vượt ra ngoài việc chỉ mô tả quy trình đơn thuần để giúp người dùng đưa ra quyết định tốt hơn
  • Đối với người viết tài liệu kỹ thuật, việc cung cấp bối cảnh và thông tin mà người dùng cần là rất quan trọng
  • Các dự án trong ngành có chức năng tương tự được khuyến nghị gồm Confluence và Notion

Bài viết liên quan

1 bình luận

 
GN⁺ 2024-10-20
Các ý kiến trên Hacker News

  • Tôi viết về bộ máy quan liêu của Đức, và hoàn toàn đồng ý với cách tiếp cận này
    Phần lớn các hướng dẫn của tôi bắt đầu bằng “đây là gì, ai cần làm, và vì sao cần làm”. Nếu không giúp mọi người xác nhận rằng họ đang làm đúng việc vì đúng lý do, họ có thể đi rất xa theo hướng hoàn toàn sai
    Hầu hết website của chính phủ không giải thích những điều này, mà chỉ yêu cầu những gì cần thiết để hoàn tất thủ tục thuộc phạm vi của họ. Họ không xem đó là một phần của quyết định lớn hơn, và giả định rằng người dùng đã biết mình đang làm gì khi tới đó

    • Liên quan đến đoạn cuối, website của chính phủ Anh làm phần này rất tốt. Có một trang đích giải thích thủ tục, sau đó đưa ra cảnh báo và lưu ý, rồi mới cho bạn điền biểu mẫu thực tế
      Hãy thử nhấn “Start Now” ở kết quả Google về gia hạn giấy phép lái xe này: https://www.gov.uk/renew-driving-licence thì bạn sẽ hiểu ý tôi
      Với tư cách “power user”, đôi khi cảm giác hơi vướng víu, nhưng tôi hiểu rằng họ phải tính đến tất cả mọi người
    • Đọc bình luận này khiến tôi nghĩ có lẽ bạn sẽ thích Every Page Is Page One. Ý chính là mọi người có thể đi vào một trang tài liệu từ bất kỳ trang nào trên site, nên mọi trang đều phải nhanh chóng cung cấp ngữ cảnh và giúp người dùng dễ dàng đánh giá liệu họ có đang đi đúng hướng hay không
      Tên sách cũng xuất phát từ đó. Bất kỳ trang nào trên site cũng có thể là trang đầu tiên đối với người dùng
    • Ước gì nhiều tài liệu kỹ thuật hơn có cách tiếp cận này. Tôi là kiểu người luôn thắc mắc vì sao phải làm theo một cách nào đó, nên hay bị rẽ nhánh và chậm lại

  • Điều này rất hợp với cách dùng LLM. Tôi luôn yêu cầu đưa ra các lựa chọn, rồi tự quyết định lựa chọn nào trong đó hợp lý nhất
    Về bản chất, tôi đang dùng nó như một thứ tài liệu kỳ lạ, gần như ma thuật, có thể phun ra một cách không hoàn hảo nhưng hữu ích các lựa chọn khả dĩ ở từng thời điểm ra quyết định

    • Hãy nghĩ tới một người học việc làm dưới trướng một nghệ sĩ nổi tiếng như Leonardo. Bậc thầy vẽ đường nét và phác thảo, còn học trò lấp đầy các phần trống dưới sự giám sát. Đôi khi bậc thầy cũng đánh cắp ý tưởng của học trò
    • Bạn có thể cho một ví dụ về cách này không?

  • Rất hay. Ngắn gọn, đi thẳng vào trọng tâm và sâu sắc. Tôi nghiêng về lối tư duy nhìn bức tranh lớn, nên không chỉ cách làm của một thứ quan trọng, mà cả lý do vì sao, và nó kết nối với bối cảnh rộng hơn như thế nào cũng quan trọng
    Tôi khuyến khích các lập trình viên tích cực dùng trường Description trong Jira story và task để đưa vào phần tóm tắt vì sao chúng ta làm việc này và nó liên hệ với bức tranh lớn ra sao. Có vẻ một số người không thích, nhưng một số lại khá thích
    Tôi thấy tốt vì có thể cung cấp bức tranh lớn của dự án, còn các lập trình viên thì hài lòng vì hiểu được bức tranh lớn đó và nhờ vậy có thể làm việc độc lập hơn

  • Việc đo xem tài liệu có giúp mọi người đưa ra quyết định tốt hay không có vẻ khó hơn nhiều so với đo xem nó có giúp họ hoàn thành tác vụ thành công hay không
    Lý do người ta tối ưu cho tài liệu theo tác vụ/quy trình là vì công ty yêu cầu nhóm tài liệu chứng minh giá trị của mình, có nhu cầu đối với loại tài liệu này, và có nhiều cách để đo lường, báo cáo trong thời gian ngắn
    Nhưng câu hỏi “bộ tài liệu này có giúp ai đó xây dựng đúng thứ theo đúng cách không” là mức mà ngay cả tổ chức cũng khó trả lời về chính sản phẩm của mình; khi trừu tượng hóa thành hiệu quả của tài liệu thì nó trở nên rất mơ hồ
    Không phải là không thể viết tài liệu giúp ra quyết định, mà là rất khó chứng minh bằng con số rằng mình đã làm được như vậy. Tôi có thể xếp hạng mức độ các bộ tài liệu khác nhau hỗ trợ người dùng cần ra quyết định và giải thích cơ sở, nhưng không rõ làm sao định lượng điều đó theo cách công ty mong muốn
    Tôi cũng tò mò cấu trúc của một bộ tài liệu được thiết kế để hỗ trợ ra quyết định sẽ khác tài liệu hỗ trợ tác vụ như thế nào. Các nhóm lớn có lẽ vẫn là khái niệm, tham chiếu và hướng dẫn, nhưng có lẽ sẽ có nhiều tài liệu khái niệm hơn hẳn và nhiều không gian hơn để đặt các khái niệm vào ngữ cảnh. Tôi cũng dự đoán sẽ có nhiều phụ thuộc giữa các chủ đề và nhiều tham chiếu chéo hơn

    • Điều thú vị là suy nghĩ đầu tiên không phải “mình dùng điều này thế nào để cải thiện tài liệu mình viết” mà là “mình chứng minh thế nào rằng điều này cải thiện tài liệu mình viết”. Có vẻ bạn đang làm việc trong một môi trường khá khắt khe
    • Ở những nơi bạn có thể tự do làm điều mình nghĩ là tốt nhất cho người dùng, như dự án cá nhân, rất có khả năng sẽ lấy hỗ trợ ra quyết định làm nền tảng cho chiến lược tài liệu
      Từ góc độ làm việc có trách nhiệm, nếu tôi cảm thấy “hỗ trợ ra quyết định” là điều tốt nhất cho dự án của mình, thì có lẽ tôi cũng có nghĩa vụ đưa chiến lược này vào tài liệu công việc
      May là tôi không bị các quản lý thiển cận bóp nghẹt, nhưng nếu phải thuyết phục ở nơi làm việc thì tôi sẽ làm thế này. Trước hết giải thích logic của chiến lược. Hỗ trợ ra quyết định là hợp lý và cũng có sức thuyết phục. Tài liệu theo tác vụ vẫn sẽ được viết, nhưng tác vụ chỉ là một tập con của hỗ trợ ra quyết định
      Tiếp đó, đưa ra một danh sách dài các ví dụ từ ticket hỗ trợ, thảo luận trong phòng chat, v.v. nơi vấn đề là thiếu hỗ trợ ra quyết định. Để giữ sự trung thực về mặt trí tuệ, tôi sẽ trình bày cả danh sách đầy đủ các ticket hỗ trợ liên quan đến tài liệu và tập con trong đó liên quan đến hỗ trợ ra quyết định. Nếu tỷ lệ không thể bỏ qua, ví dụ 25%, thì cần xem xét “hỗ trợ ra quyết định” sâu hơn
      Cuối cùng, các bên liên quan có thể nêu ví dụ họ từng gặp trong công việc của mình. Kiểu như “còn nhớ lúc rất khó quyết định nên chuyển CMS sang cái gì không?”

  • Thường thì tôi gọi đây là cách tiếp cận heuristic
    Tôi cảm thấy công việc cần một cách tiếp cận kiểu logic mờ. Tuy nhiên, nó hoạt động tốt nhất khi kỹ sư đã có một mức kinh nghiệm nhất định
    Nếu thiếu kinh nghiệm, dù có giỏi và thông minh, vẫn phải chỉ dẫn cụ thể hơn nhiều

    • Thinking in Bets là một trong những cuốn sách hữu ích nhất đối với cách tôi tiếp cận kỹ thuật phần mềm. Nó không phải sách về code, mà là sách về cách đưa ra quyết định hiệu quả trong môi trường thông tin hạn chế
    • Tôi không rõ tiếp cận công việc theo kiểu logic mờ nghĩa là gì. Bạn có thể giải thích thêm một chút không?

  • Một cách tiếp cận tốt để đưa ra quyết định trong bối cảnh nhóm được Rich Hickey giải thích ở đây: https://www.youtube.com/watch?v=c5QF2HjHLSE
    Tiêu đề bài nói là “Design in Practice”, nhưng thực ra nội dung nói về ra quyết định

  • “Công việc chỉ là tất cả những gì phải làm để đi từ quyết định này sang quyết định tiếp theo.” — Venkatesh Rao, Tempo

  • Tôi cũng từng lập luận điều tương tự. Đừng chỉ mô tả công cụ ở mức cao; đặc biệt là mọi người thường chuyển sang chế độ marketing, trong khi cần nói công cụ đó được thiết kế để giải quyết vấn đề gì và đã đánh đổi những gì trong quá trình đó.
    Khi đó sẽ dễ hơn nhiều để đặt công cụ cùng các lựa chọn, chế độ khả dụng, v.v. vào đúng ngữ cảnh, và nhanh chóng phán đoán liệu nó có phù hợp với mình hay không.

  • Lời khuyên này hơi khó hiểu. Quyết định của ai? Quyết định của người tạo công cụ, hay của người dùng?
    Nhìn chung, nó có vẻ là sự đơn giản hóa quá mức. Trước hết, sẽ hữu ích hơn nếu hiểu tài liệu mình đang viết thuộc loại nào: dùng để học, hướng tới mục tiêu, để hiểu, hay cung cấp thông tin [1].
    Ví dụ, khi đang tra API của một hàm nào đó mà bị dội một đống thông tin về “quyết định” thì có thể sẽ bực mình.
    1 - https://www.writethedocs.org/videos/eu/2017/the-four-kinds-o...

    • Tài liệu luôn phải xử lý nhu cầu của người dùng. Điều đó không biến mất. Diataxis, bốn góc phần tư của tài liệu được nhắc tới, cũng vậy.
      Tôi nghĩ lý do bài viết này tạo được sự đồng cảm là vì nó chỉ ra điểm mù của hai chiến lược nổi tiếng. Ai cũng cố làm tài liệu lấy người dùng làm trung tâm, và nhiều đội làm theo Diataxis, nhưng vẫn gặp khó khăn trong việc giúp người đọc hoàn thành việc bằng tài liệu.
      Nếu bắt đầu từ góc nhìn cơ bản rằng “tài liệu phải hỗ trợ quyết định”, đó có thể là một con đường để làm tài liệu hữu ích hơn.

  • Việc biết mọi người dùng hệ thống của tôi như thế nào để đưa ra quyết định là rất quan trọng. Tôi cho rằng kiến thức đó là thiết yếu để bảo trì, mở rộng hoặc xây mới hệ thống.
    Nhưng bài viết đề xuất một trách nhiệm cao hơn: phải ghi lại quy trình ra quyết định của người dùng, và cho họ biết bối cảnh, các lựa chọn, cũng như hệ quả của quyết định.
    Tôi từng làm trong một “hệ thống hỗ trợ ra quyết định” có trách nhiệm như vậy, và nó trở nên phức tạp rất nhanh. Mọi người thích tranh luận về hệ quả ngay cả khi hệ quả đó đã được biết chắc 100%. Họ cũng ghét các email tự động chứa sự bất định, và ghét việc tài liệu buộc họ vào lựa chọn nhị phân trong khi thực tế có nhiều lựa chọn hơn rất nhiều.
    Vượt ra ngoài bài viết này, tôi mong cuốn sách bàn đến khái niệm kiểm soát. Để tài liệu hóa một hành vi nào đó, cần có một mức độ bảo đảm hoặc cưỡng chế nhất định đối với hành vi đó thì tài liệu mới giữ được thẩm quyền. Cá nhân tôi xem sự thiếu vắng thẩm quyền và kiểm soát là một điểm mù phổ biến và lớn của các sáng kiến viết lách như https://www.plainlanguage.gov.

    • Trích lại những gì tôi từng viết về bài này trên r/technicalwriting: điều thật sự quan trọng trong ý tưởng của Baker là giáo lý đào tạo viết tài liệu kỹ thuật gần như tuyệt đối xoay quanh việc lấy tác vụ làm trung tâm.
      Nếu khảo sát các cây viết tài liệu kỹ thuật chuyên nghiệp, phần lớn có lẽ tin rằng “giúp người dùng hoàn thành tác vụ” là mục tiêu chính của tài liệu, thậm chí là MỤC TIÊU chính.
      Trích dẫn ngắn của Baker khá cấp tiến theo nghĩa Latin của từ này: “trở về gốc rễ”. Nó gợi ý rằng một trong những giả định nền tảng của chúng ta đang thiếu hụt nghiêm trọng.
      Cá nhân tôi thấy ý tưởng của Baker thú vị vì nó đặt ra một tiêu chuẩn cao hơn nhiều so với tiêu chuẩn hiện đang được kỳ vọng ở tài liệu kỹ thuật. Nhiều tài liệu mặc định rằng chỉ cần tác vụ được ghi lại là “nhiệm vụ hoàn thành”, nhưng Baker dường như nói rằng như vậy vẫn chưa đủ.
      Tất nhiên tác vụ vẫn cần được tài liệu hóa, nhưng tác vụ là một tập con của thông tin cấu thành quyết định.
      Tôi không nhớ cuốn sách của Baker có bàn về kiểm soát theo cách được nói ở đây hay không. Với tôi đây là một ý tưởng mới, nên cảm ơn bạn.
      Một ví dụ cụ thể về kiểm soát hiện ra trong đầu tôi là thế này. Phần lớn tài liệu của tôi phụ thuộc vào các trang của những dự án mã nguồn mở khác; nếu chất lượng các trang bên ngoài đó thấp, thì rất có thể việc cải thiện tài liệu đó cũng phải là trách nhiệm của tôi. Nhiều người có thể xem tài liệu nằm ngoài site của mình là ngoài phạm vi trách nhiệm, nhưng nếu thật sự muốn hỗ trợ quyết định, thì ai host tài liệu đó không quan trọng.
      Có lẽ có nhiều điều đáng học từ thái độ trở thành một công dân mã nguồn mở tốt.