Tại sao Tài liệu về Sản phẩm Công nghệ lại Khó sử dụng đến vậy? (theo Quan điểm của Người dùng)

Ngày nay, tài liệu của chúng tôi về các công cụ dành cho nhà phát triển rất khó sử dụng và chúng tôi có xu hướng tìm giải pháp trên các nguồn khác như Youtube, sự cố GitHub hoặc các bài đăng trên blog. Nội dung của nó có thể dễ dàng bị tụt hậu hoặc điểm mấu chốt hoàn toàn không được đề cập đến. Tôi coi vấn đề này là một vấn đề nổi cộm mà chúng ta nên giải quyết càng sớm càng tốt và tôi nghĩ cần giải quyết hai vấn đề chính trước tiên. (Theo quan điểm của người dùng)

• Tài liệu quá khó để đóng góp
  • Tài liệu dễ dàng trở nên lỗi thời. Mọi người có xu hướng viết một bài đăng trên blog hơn là đóng góp vào một tài liệu bởi vì nó đòi hỏi nhiều nỗ lực hơn mà không có các ưu đãi tương ứng.
• Bối cảnh được nhóm lại

  • Bản thân tài liệu hầu như không kết nối với các tài nguyên khác. Bối cảnh tạo ra tài liệu tốt được nhóm lại.

    
    

Trong bài viết này, tôi muốn giới thiệu hai khái niệm xoay quanh tài liệu mà tôi nghĩ là có vấn đề và sau đó mở rộng hơn thành 3 quan điểm tư duy để giải quyết hai vấn đề này.

Trước hết, hãy nhớ lại một số tài liệu bạn đã truy cập gần đây và cùng tôi giải thích bên dưới. Tôi muốn lấy Next.js làm ví dụ, hiện đang là tài liệu tôi truy cập nhiều nhất. Hãy bắt đầu với trang "Bắt đầu".

https://nextjs.org/docs/getting-started

Tài liệu của Nextjs có cấu trúc phổ biến thông qua các sản phẩm khác nhau, hãy để tôi gọi cấu trúc này là "Cấu trúc danh sách biệt lập". Lý do tôi gọi chúng là cô lập là chúng chủ yếu được duy trì bởi những người đứng sau Next.js (mặc dù chúng có nguồn mở).

Hơn nữa, tôi muốn kết luận suy nghĩ đằng sau tài liệu này là "Điểm nhấn của chủ sở hữu".

Dấu đầu dòng của chủ sở hữu

Lý do tôi gọi nó là "Điểm nhấn của chủ sở hữu" là quá trình tạo tài liệu thường do chủ sở hữu sản phẩm thực hiện. Khi bắt đầu một sản phẩm, không ai có sự hiểu biết tốt hơn chủ sở hữu. Chủ sở hữu là người tốt nhất để duy trì tài liệu thích hợp cho người tiêu dùng và người bảo trì của họ.

Nhưng sau một thời gian, sản phẩm nhận được rất nhiều sự yêu thích và bắt đầu gây dựng được cộng đồng. Việc theo dõi các trường hợp góc và lỗi ngày càng trở nên khó khăn hơn. Chủ sở hữu phải nắm bắt các cam kết mới và giải quyết các vấn đề hàng ngày, mặt khác, họ phải giải thích các thiết kế mới, và cung cấp thông tin cho những người mới đến để khắc phục những vấn đề này. Tải trọng đang tăng cao đáng kể.

Không phải mọi sản phẩm đều có thể bắt kịp, nội dung bắt đầu tụt hậu và một số giải pháp có thể tồn tại trong các bài đăng trên blog của người khác, câu trả lời của StackOverflow, các vấn đề trên GitHub hoặc các cuộc thảo luận. Người dùng cần kết nối các giải pháp này với các công cụ tìm kiếm, đôi khi giải pháp trên tài liệu thậm chí còn sai.

Cấu trúc danh sách biệt lập

Cấu trúc danh sách tách biệt rất phổ biến, trong thương mại điện tử, trong các trang web có mục đích chung, trên điện thoại của bạn và trong tài liệu. Nó ở mọi nơi.

Cấu trúc phần lớn là tùy ý và cố chấp xuất phát từ tư duy "gạch đầu dòng của chủ sở hữu", do trước tiên chủ sở hữu phải đưa ra cây của cấu trúc, theo thứ tự mà họ cho là phù hợp nhất với khách hàng của họ.

Cấu trúc liệt kê biệt lập là một con dao hai lưỡi: Nói rõ ràng, tôi không hoàn toàn phản đối cấu trúc này, nó thực sự hữu ích trong bối cảnh chung. Ví dụ, nó rất tốt cho việc khám phá ban đầu và nếu bạn đã quen thuộc với tài liệu, bạn sẽ khá dễ dàng tìm thấy thông tin mình muốn.

Nhưng mặt khác, đó là một cấu trúc cố định, rất khó để cấu trúc phát triển và mỗi khi người bảo trì muốn thêm thứ khác, thật khó để tìm được vị trí thích hợp nếu ngay từ đầu chủ nhân đã không nghĩ kỹ. Bên cạnh đó, người dùng không có lựa chọn nào khác ngoài việc khám phá tài liệu của bạn. Họ chỉ có một tuyến đường và nó không đủ.

Hãy tưởng tượng một cấu trúc động, giống như một biểu đồ hướng lực (Một cái gì đó như Obsidian có thể hoàn thành hoặc một biểu đồ cây, bạn có thể tìm thấy nhiều ví dụ ngay trong phần xuất bản của chúng [^ 1]). Tôi không nói biểu đồ hướng lực hoặc biểu đồ hình cây tốt hơn các cấu trúc liệt kê biệt lập. Điều tôi muốn là khuyến khích mọi người không nên suy nghĩ theo kiểu "liệt kê" mà hãy theo hướng "năng động" hơn, để mọi người có thể chọn bất cứ thứ gì phù hợp với nhu cầu của họ nhất. Họ có thể sử dụng sơ đồ cây để khám phá cấu trúc và sử dụng biểu đồ hướng lực để xác nhận mối liên hệ giữa các chủ đề. Hoặc chúng tôi có thể đưa ra một cấu trúc mới từ đầu có thể giải quyết một số vấn đề này.

Kết hợp lại, tư duy và cấu trúc dẫn đến vấn đề mà tôi nghĩ là có vấn đề, được liệt kê dưới đây.

Tài liệu quá khó để đóng góp

Kết hợp với tư duy độc đoán về "Điểm nhấn của chủ sở hữu" và "Cấu trúc danh sách biệt lập", những gì chúng tôi có là tài liệu hiện tại chỉ có thể được duy trì đúng cách bởi chủ sở hữu, không có cách nào khác dễ dàng hơn để đóng góp vào tài liệu. Vấn đề là gấp đôi.

Đầu tiên, dựa trên tư duy "Dấu đầu dòng của chủ sở hữu", tác giả không muốn một số người thiếu kinh nghiệm làm rối tài liệu của bạn và khá khó để phù hợp với giọng điệu của tài liệu nếu bạn không dành nhiều thời gian để phù hợp với những người bảo trì của mình.

Thứ hai, người dùng của bạn không có bất kỳ động cơ nào để đóng góp vào tài liệu, mọi người yêu thích sản phẩm của bạn nhưng nếu họ không nhận được bất kỳ tín dụng nào trong quá trình xây dựng tài liệu hoặc một số quyền sở hữu đối với một số trang tài liệu, thì sẽ không có động lực nào.

Bạn có thể tranh luận rằng họ có thể đăng một vấn đề và giải thích đề xuất của họ nhưng vấn đề vẫn còn. Cảm giác đóng góp rất đồng thời, nó giống như cảm giác mua một thứ gì đó. Hãy tưởng tượng một thế giới song song, ở đây, nếu bạn muốn mua một thứ gì đó, bạn cần viết ra 200 từ để mô tả lý do tại sao bạn muốn mua thứ này và lợi ích của cộng đồng là gì.

Không cần phải ngăn cản mọi người đóng góp tài liệu với bộ máy hành chính. Chúng tôi cần đưa ra một cấu trúc khác có thể duy trì quyền hạn của tài liệu và đồng thời mang lại lợi ích cho sự đóng góp.

Bối cảnh được nhóm lại

Nội dung của tài liệu tốt không chỉ là tài liệu mà còn là các cuộc thảo luận, vấn đề, bài đăng blog và video tương ứng. Tôi sẽ gọi những tài liệu này là "Contexts".

Cho đến gần đây, chúng tôi có xu hướng lưu trữ các ngữ cảnh này một cách phân tán. Một dự án nguồn mở thông thường lưu trữ thảo luận của họ trong thảo luận GitHub hoặc diễn đàn nghị luận, các trường hợp sử dụng của họ trong các trang web sản phẩm, các vấn đề ngay trong các vấn đề GitHub và một trang web tài liệu tự lưu trữ ở những nơi khác. Bên cạnh đó, có rất nhiều nội dung do cộng đồng tạo ra trên YouTube và các bài đăng trên blog cá nhân.

Trong thực tế, bối cảnh của một sản phẩm trở nên nhóm lại. Chúng sẽ không có liên kết với nhau. Có thể có một cuộc thảo luận về giải pháp cho lỗi cụ thể, nhưng không có liên kết ngược lại trên phần tài liệu đã đề cập đến giải pháp này. Đáng buồn là chúng ta phải đối mặt với thực tế rằng liên kết hai chiều không phải là khả năng của internet hiện tại.

Bối cảnh theo cụm dễ thay đổi

Hãy tưởng tượng một tình huống mà bạn xem tài liệu của sản phẩm và nhanh chóng phát hiện ra rằng tài liệu đó không cung cấp giải pháp, sau đó vào ngày bạn tìm thấy giải pháp khả thi trên bài đăng blog của người khác.

Tại thời điểm này, với tài liệu hiện tại, không có cách nào khác để nhắc nhở các nhà phát triển khác rằng họ có thể giải quyết vấn đề tương tự bằng phương pháp này được mô tả bởi bài đăng trên blog, bạn không thể thêm tham chiếu vào tài liệu. Những gì bạn có thể làm là mở một vấn đề (nếu đó là mã nguồn mở) hoặc mở một cuộc thảo luận trên một diễn đàn để nhắc nhở mọi người về giải pháp này sẽ sớm bị tràn ngập bởi các nội dung khác.

Mọi giải pháp hữu ích trong bất kỳ bối cảnh nào đều cần phải có khả năng chống lại lũ lụt thông tin mà chúng ta có ngay bây giờ. Họ phải tham gia chiến trường này mà không có điểm neo nào ngoài các công cụ tìm kiếm.

Danh sách tuyệt vời [^ 2] là một ý tưởng hay, chúng cung cấp một cách để giữ lại nội dung tốt, nhưng chúng có cùng một vấn đề với "Cấu trúc danh sách biệt lập" và tư duy "Dấu đầu dòng của chủ sở hữu".

Nếu tình hình vẫn như cũ…

Hệ quả ngay lập tức của những vấn đề này là “Tài liệu” sẽ bị phân hủy theo thời gian. Bạn có thể xem qua một số tài liệu của gã khổng lồ công nghệ bao gồm tài liệu về các dịch vụ web của Amazon hoặc tài liệu về đám mây của Google, tất cả chúng đều choáng ngợp và khó đọc.

Cảm giác tồi tệ nhất là bạn bị mắc kẹt vào một vấn đề cụ thể mà bạn không thể tìm thấy trong tài liệu và bất kỳ nơi nào khác. Chúng tôi sẽ phải đối mặt với những loại tình huống này nhiều hơn nếu cấu trúc tài liệu của chúng tôi không thể phù hợp với phạm vi sản phẩm chúng tôi sử dụng.

Có vẻ như quá sức khi nghĩ ra một loại cấu trúc mới để khắc phục những vấn đề này ngay từ đầu. Nhưng nhìn kỹ lại, chúng ta có thể tách các vấn đề tổng thể thành 3 câu hỏi để tự hỏi bản thân.

• Làm thế nào để khuyến khích người dùng đóng góp vào tài liệu và không can thiệp vào mục đích chung của tài liệu? Chúng ta có thể có trải nghiệm tương tác nhiều hơn cho tài liệu không? Người dùng có thể trực tiếp đóng góp vào tài liệu mà không cần rời khỏi trang không?

• Làm thế nào để tập hợp ngữ cảnh lại với nhau để có trải nghiệm tìm kiếm tốt hơn mà không dựa vào các giải pháp tìm kiếm bên ngoài và mang lại khả năng kết nối giữa mọi ngữ cảnh trong suốt quá trình?

• Làm thế nào để thử nghiệm với một cấu trúc mới có thể mang lại lợi ích cho trải nghiệm người dùng và lặp lại nó theo thời gian hoặc thậm chí để người dùng tự do lựa chọn?

  
  

https://twitter.com/EiffelFly

[^ 1]: Trang xuất bản Obsidian [^ 2]: sindresorhus / awesome