Ví dụ là tài liệu tốt nhất

 (rakhim.exotext.com)
38 điểm bởi GN⁺ 2025-10-11 | 8 bình luận | Chia sẻ qua WhatsApp
  • Khi lập trình viên tìm kiếm tài liệu, 95% trường hợp chỉ cần một ví dụ đơn giản là đủ, nhưng số trường hợp có thể tìm thấy ví dụ trong nguồn chính thức chỉ chiếm 5%
  • Tài liệu kỹ thuật chính thức về cơ bản được viết cho những người đã đắm mình sâu trong hệ sinh thái đó, nên với các lập trình viên phải qua lại giữa nhiều dự án và ngôn ngữ, việc khôi phục lại ngữ cảnh đòi hỏi một lượng năng lượng tinh thần đáng kể
  • Nếu nhìn vào tài liệu của hàm max() trong Python, sẽ có rất nhiều kiến thức nền cần có để hiểu cú pháp định nghĩa hàm và các khái niệm liên quan, nhưng chỉ cần 5 dòng ví dụ đơn giản là có thể hiểu ngay
  • clojuredocs.org của cộng đồng Clojure cung cấp tài liệu thực dụng thông qua các ví dụ do người dùng đóng góp, và là một điển hình tốt khi còn bao gồm cả các hàm liên quan để tăng khả năng ứng dụng thực tế
  • Ngay cả các dự án phần mềm lớn cũng hiếm khi cung cấp đủ 4 loại tài liệu, nên các lập trình viên thường đi tìm tutorial không phải vì cần được dẫn dắt mà vì họ cần ví dụ

Tầm quan trọng của ví dụ khi tìm tài liệu

  • Khi lập trình viên tìm tài liệu, 95% trường hợp chỉ cần đúng một ví dụ là đủ
  • Nhưng số trường hợp có thể tìm thấy ví dụ trong nguồn chính thức chỉ chiếm 5%
  • Phần lớn tài liệu kỹ thuật chính thức được viết mặc định cho những người đã đắm mình sâu trong hệ sinh thái
  • Nhiều lập trình viên hằng ngày phải đồng thời tung hứng nhiều "thế giới" trong đầu
    • Việc chuyển đổi giữa dự án, ngôn ngữ và framework diễn ra thường xuyên
    • Tốn khá nhiều năng lượng tinh thần để khôi phục ngữ cảnh và hiểu tình huống

Phân tích trường hợp tài liệu Python

  • Ví dụ về hàm max() trong tài liệu Python 3
    • max(iterable, /, *, key=None): trả về phần tử lớn nhất
    • Sau đó là phần giải thích kéo dài trong 5 đoạn ngắn
  • Để hiểu tài liệu này, những kiến thức Python cần phải biết gồm
    • ý nghĩa của * trong định nghĩa hàm
    • ý nghĩa của / trong định nghĩa hàm
    • khái niệm "positional-only parameter separator"
    • khái niệm iterable
    • khái niệm keyword-only arguments
    • ý nghĩa thông thường của tham số key
  • Phải đọc phần văn bản thì mới có thể hiểu được nên truyền giá trị gì và cách thực sự gọi hàm

Hiệu quả của ví dụ đơn giản

  • Tác giả thừa nhận rằng không thể lược bỏ các chi tiết quan trọng chỉ để đổi lấy sự ngắn gọn
  • Tuy nhiên, lý do nhiều lập trình viên tìm đến trang đó đơn giản là để nhanh chóng xem cách truyền một hàm sắp xếp tùy chỉnh (key) vào hàm max
  • Nếu có ví dụ như bên dưới thì có thể nhận ngay thông tin mình cần 
    max(4, 6) # → 6  
max([1, 2, 3]) # → 3  
max(['x', 'y', 'abc'], key=len) # → 'abc'  
max([]) # ValueError: max() arg is an empty sequence  
max([], default=5) # → 5
  • Nhờ ví dụ mà có thể hiểu một cách dễ dàng và trực quan

Thực tiễn tốt từ cộng đồng Clojure

  • clojuredocs.org là một dự án do cộng đồng Clojure xây dựng
    • Người dùng đóng góp ví dụ cho các hàm tích hợp sẵn
    • Đây là một tài nguyên không thể thiếu trong việc lập trình hằng ngày
  • Các trang ví dụ: tham khảo into, spit, map
  • Đặc điểm của các ví dụ
    • Không chỉ có chính hàm đó mà còn bao gồm cả các hàm liên quan
    • Nâng cao tính thực dụng và khả năng áp dụng thực tế

Giới hạn của cách làm tài liệu hiện nay

  • Ngay cả các dự án phần mềm lớn cũng hiếm khi cung cấp đủ 4 loại tài liệu
  • Lý do khiến người ta ngần ngại khi bấm vào liên kết "Documentation"
    • Đa phần đó là API reference được sinh tự động, súc tích nhưng khó đọc
  • Lý do thực sự khiến lập trình viên tìm tutorial
    • Không phải vì họ cần được hướng dẫn, mà vì họ cần ví dụ
    • Tutorial hữu ích hơn vì có chứa ví dụ

Bài viết liên quan

8 bình luận

 
sonnet 2025-10-12

Thành thật mà nói, có vẻ đây là câu chuyện chủ yếu đúng với Java và Python. Đó cũng là những hệ sinh thái có chủ nghĩa đề cao ngôn ngữ riêng và văn hóa bị cô lập khá mạnh về mặt paradigm. Đặt theo Python thì nội dung này khá đúng, nhưng khi học nhiều ngôn ngữ khác nhau thì khoảng 5% nghe có vẻ bị phóng đại đáng kể.
 
kuber 2025-10-12

Ví dụ chính là tài liệu tốt nhất.

Hãy đến với Golang, nơi code chính là tài liệu~
Bọn mình phát triển bằng cách đọc cả test code ngay cả khi không có README
 
pjtco 2025-10-11

Tôi cứ tưởng chỉ mình tôi đầu óc chậm chạp nên không hiểu nổi tài liệu chính thức thôi chứ haha
Thật sự chỉ cần quăng ra ví dụ rồi giải thích thêm một chút là hiểu rất nhanh.....
 
nemorize 2025-10-11

Có lẽ PHP vừa là ví dụ tốt vừa là ví dụ tệ nhất.

Nó là một ví dụ hay ở chỗ có thể tải lên nội dung do người dùng đóng góp vào tài liệu chính thức, nên có thể tham khảo nhiều ví dụ mã khác nhau,

...nhưng PHP lại là ví dụ tệ nhất ở chỗ các hàm dựng sẵn có quá nhiều khác biệt tinh vi về BC, mà những ví dụ đóng góp thì toàn từ thời xưa như trái đất, nên lẫn vào đó là những thứ hơi khác với cách hoạt động thực tế, chỉ càng làm tăng thêm sự hỗn loạn... haha.. ha...
 
savvykang 2025-10-11

Nếu nhìn vào tài liệu phát triển iOS hay Cocoa trước đây, thường có hẳn một mục use case riêng; chẳng phải đó mới là cách viết tài liệu đúng đắn sao? Cần có đủ cả ví dụ, chữ ký hàm và phần mô tả cách hoạt động.
 
aer0700 2025-10-11

Ví dụ là tài liệu tốt nhất.

Nếu trước đây sự thiếu thốn của docs chính thức được bù đắp bằng Stack Overflow và Google, thì dạo này có vẻ LLM đang lấp vào chỗ trống đó.
 
GN⁺ 2025-10-11
Ý kiến trên Hacker News

  • Điểm hay nhất của Python ngày xưa là khi mở tài liệu thư viện ra, bạn sẽ thấy phần liệt kê rõ ràng các tham số hàm và giá trị trả về. Dạo gần đây, nhiều tài liệu thư viện JavaScript hoặc Python chỉ đưa ví dụ, điều này khá đáng tiếc. Nếu muốn làm nhanh một thứ gì đó thì ví dụ rất tốt, nhưng để sửa lỗi hoặc học một thư viện thì phần mô tả tham số là thiết yếu. Ví dụ là phần cộng thêm thì tốt, nhưng không nên là toàn bộ tài liệu

    • Thực ra thứ bạn muốn là định nghĩa kiểu. Định nghĩa kiểu đóng vai trò như tài liệu tốt. Công cụ của hệ thống kiểu đã hiển thị sẵn rất nhiều thông tin ngay trong editor hoặc IDE, nên nhu cầu tự đi tìm và đọc tài liệu giảm đi. Việc tài liệu thiên về ví dụ ngày nay cũng là do thay đổi trong quy trình làm việc đó. Người ta cho rằng không cần lặp lại trong tài liệu những gì công cụ kiểu đã cung cấp. Khi xem tài liệu, tôi quan tâm nhiều hơn đến việc “công cụ này giải quyết được vấn đề gì” thay vì chi tiết từng tham số. Ví dụ cực kỳ giỏi trong việc cho thấy khả năng đó. Khi muốn giải quyết một bài toán cụ thể, nhìn ví dụ là có thể nhanh chóng đánh giá công cụ đó có hữu ích hay không. --- nếu có hệ thống kiểu thì tôi muốn xem ví dụ trước. Nếu không có hệ thống kiểu thì 1) tôi không hài lòng. 2) tôi vẫn muốn xem ví dụ trước, rồi sau đó là mô tả chi tiết về tham số/giá trị trả về/cấu trúc dữ liệu

    • Tài liệu tốt cần cả hai. Trước tiên là giải thích chi tiết, sau đó thêm nhiều ví dụ khác nhau để người đọc kiểm chứng nội dung. Đôi khi chỉ ví dụ là đủ, nhưng nếu số lượng tổ hợp tùy chọn quá nhiều thì gần như không thể biểu diễn hết bằng ví dụ. Vì vậy cần mô tả từng tùy chọn trước, rồi chuẩn bị ví dụ cho càng nhiều trường hợp càng tốt để người đọc có thể tự vận dụng. Và tài liệu tốt thì cực kỳ khó làm, nên ngày nay rất hiếm thấy

    • Tôi không hoàn toàn đồng ý. Tài liệu kiểu Javadoc là tài liệu lập trình dựa trên type và docstring nội tuyến. Nó là thứ bắt buộc phải có, nhưng không nhất thiết phải lên web; xem ngay trong mã nguồn hiệu quả hơn. Còn ví dụ hay hướng dẫn QuickStart thì cũng absolutely cần thiết. Chúng giúp hạ thấp rào cản tiếp cận thư viện. Chỉ nhìn mã nguồn thì không dễ hiểu được cách dùng API. Trước đây nhiều thư viện Java chỉ cung cấp Javadoc, nên tôi từng rất khó chịu vì không biết dùng ra sao

    • Tôi nghĩ ví dụ có chú thích tốt là tuyệt nhất. Nhưng nó không thể thay thế tài liệu truyền thống

    • Tôi tự hỏi liệu bạn có từng nghĩ rằng người khác có thể có phong cách học khác mình không. Tôi không hiểu vì sao lại phản đối chuyện ví dụ là một phần của tài liệu. Ví dụ giúp giảm ma sát khi phải chuyển đổi ngữ cảnh trong nhiều tình huống khác nhau

  • Các trang man của Unix cũng rất cần ví dụ. Chúng thường chỉ được viết như tài liệu tham chiếu cho người vốn đã rành công cụ, nên hoàn toàn không giúp ích gì cho người mới. Tài liệu tốt cần cả hai thứ

    • Hoàn toàn đồng ý. Tôi muốn nhắc các tác giả của mọi trang man rằng có một mục quy ước tên là EXAMPLE. Có thể tham khảo tài liệu chính thức của man(1)

    • Tôi chưa từng thấy vấn đề đó. Tôi thường cứ bắt tay viết code trước để học dần lệnh hay thuật ngữ, rồi lần lượt xem mã lỗi trả về, nguyên nhân của chúng, ý nghĩa tham số, v.v. Không có ví dụ cũng không sao nếu tài liệu đầy đủ. Ngược lại, chỉ có ví dụ mà không có bất kỳ lời giải thích nào mới thật sự là tệ nhất. Sao lại có tài liệu mà ngay cả tham số là gì, nghĩa là gì cũng không biết được?

    • Tôi thấy thú vị khi Stack Overflow trước đây cũng từng thử điều tương tự. Nó được vận hành dưới tên Stack Overflow Documentation ở bản beta từ 2016 đến 2017. Họ định tạo tài liệu lấy ví dụ làm trung tâm nhưng rồi đóng lại. Dù vậy, nội dung do cộng đồng để lại vẫn còn được công khai theo giấy phép CC BY-SA

    • Hãy thử xem cheat.sh. Tôi dùng ngay trong script bằng curl cheat.sh/"$1"

    • Tôi luôn ngạc nhiên vì thực ra có khá nhiều trang man đã có ví dụ. Dù vậy, vẫn còn rất nhiều chỗ để cải thiện một cách tổng thể hơn

  • Ví dụ không chỉ tốt cho người mới hay người dùng thỉnh thoảng mới dùng. Ngay cả người dùng thành thạo cũng cần tài liệu chuẩn, tức là tài liệu có đầy đủ mọi cấu hình tham số. Ví dụ, tài liệu requests lúc nào Google cũng đẩy tôi đến những trang toàn ví dụ kiểu Quickstart nên rất bất tiện. HTTP GET thì ai cũng biết, nhưng các tùy chọn khác là gì, timeout được xử lý thế nào, hay raise_for_status có bỏ qua 204 không thì rất khó tìm. Cần cả hai, nhưng nếu thời gian của lập trình viên có hạn thì tôi sẽ ưu tiên cung cấp tài liệu chuẩn trước. Liên kết ví dụ Quickstart của requests

    • Khi nhìn vào ví dụ, người ta có thể hiểu hành vi dễ hơn nhiều so với tài liệu kiểu tham chiếu. Con người khá kém trong việc đặt tên, khái quát khái niệm và viết tài liệu. Gần đây tôi cũng mất vài tiếng vì một tham số chỉ hoạt động trong những điều kiện nhất định. Nếu muốn lần ra code thì quá phức tạp, mà ngay cả LLM cũng nói sai rằng tham số đó không hề có tài liệu. Cuối cùng, cách hiệu quả nhất vẫn là tự viết mã ví dụ để tìm ra hành vi mình muốn. Ví dụ có thể nén rất nhiều thông tin quan trọng để kiểm chứng nhanh. Ngược lại, tài liệu API cố gắng bao quát mọi thứ nên vừa khó bảo trì vừa không truyền được trọng tâm. Và trừ khi đã rất rõ ràng, tôi tuyệt đối không tin vào hành vi của thư viện. Nếu README không cho thấy rõ hành vi hoặc type không ràng buộc nó, thì tôi luôn giả định rằng nó có thể thay đổi bất cứ lúc nào. Kết quả là tôi viết code gọi theo hướng phòng thủ tối đa

    • Ví dụ không chỉ quan trọng với người mới mà với tất cả mọi người. Một ví dụ 5 giây có thể mang lại hiệu quả tương đương cả tiếng đọc tài liệu và thử nghiệm. Một số tài liệu của git là như vậy, và những hàm về bản chất đơn giản nhưng khó giải thích cũng thế. Ngay cả khi lập trình viên chỉ làm được một thứ, họ vẫn hoàn toàn đủ sức đưa ra cả ví dụ lẫn tài liệu. Cả hai nên luôn được cung cấp, trừ những trường hợp quá hiển nhiên

    • Đồng ý. Tài liệu tốt gần như phải xác định rõ toàn bộ hành vi của chương trình, và chỉ dựa vào ví dụ thì rất khó làm được việc đó

    • Có thể có cả hai cùng lúc. Ví dụ và tài liệu kỹ thuật không hề loại trừ lẫn nhau

    • Câu chuyện về occasional users chính là điều tôi đang nói tới. Mỗi lần qua lại giữa dự án, ngôn ngữ và framework, chi phí tinh thần để khôi phục ngữ cảnh và hiểu mình đang ở đâu là rất lớn

  • Có người hay chê Perl, nhưng tài liệu của Perl thực sự hữu ích. Luôn có mục SYNOPSIS ở phía trước, đưa ra mã ví dụ có thể dùng ngay. Sau đó mới đến giải thích, tham chiếu và ví dụ bổ sung. Ví dụ: tài liệu bigrat, tài liệu Archive::Tar. Khi viết tài liệu dự án, rất nên tham khảo phong cách của Perl. Và chính phong cách đó cũng được tổng kết rất tốt

    • Tôi từng dùng Perl vào đầu những năm 2000, rồi tình cờ dùng lại vào năm 2014, và cảm giác như mọi thứ quay trở lại rất tự nhiên. Có lẽ vì góc nhìn ngôn ngữ học và thái độ của Larry Wall mà nó để lại ấn tượng sâu sắc. Không phải vì sự chính xác kiểu toán học, mà giống như “đang trò chuyện với một người bạn” hơn

  • Cần cả hai. Nhìn ví dụ thì nắm ý rất nhanh, dễ tích hợp, còn phần giải thích tham số và cấu hình chi tiết thì giúp xử lý các vấn đề phức tạp và hiểu tổng thể công cụ. Thiếu một trong hai là rất bất tiện. Tuy vậy, với những thư viện cực kỳ đơn giản thì ví dụ có thể bao quát toàn bộ

    • Cần cả ví dụ lẫn tài liệu tham chiếu. Nếu có thể, nên bổ sung thêm môi trường REPL. Nếu có thể sửa ví dụ và thử ngay, thì ngay cả khi tài liệu còn thiếu, rất nhiều nhược điểm cũng sẽ được bù đắp

  • Khung Diátaxis cho thấy rõ rằng tài liệu có nhiều loại khác nhau và mỗi loại phục vụ một mục đích riêng. Không phải cái nào là “tốt nhất”, mà điều quan trọng là chúng được dùng theo các nhu cầu khác nhau. Trang chính thức của Diátaxis

    • Chuyện này đáng lẽ phải nằm ở trên cùng. Sau từng ấy thảo luận mà mãi mới thấy nhắc đến Diátaxis thì hơi bực thật. Tôi xem ví dụ là một phần cốt lõi của tài liệu, nhưng không hẳn là một “loại tài liệu” độc lập, mà gần hơn với một “kỹ thuật tài liệu” quan trọng

    • Đúng vậy! Ví dụ (hoặc tutorial) là một trụ cột trong việc dạy một hệ thống. Tôi không chắc ai là người đầu tiên đưa ra, nhưng liên kết này có vẻ giống liên kết của tác giả ở cuối bài viết: > “Ngay cả các dự án lớn cũng hiếm khi có đủ cả 4 loại tài liệu. Vì vậy đôi khi tôi ngần ngại khi nhấp vào liên kết ‘Documentation’.” Tôi thích tài liệu thiên về giải thích. Nếu hiểu được cấu trúc hoặc lý do đằng sau cách hoạt động, thì dù là ví dụ hay tutorial cũng sẽ dễ tiếp thu hơn. Khi một technical writer hoặc educator giỏi dựng khung này ngay từ đầu thì hiệu quả rất lớn. Ngược lại, tài liệu tham chiếu API chủ yếu cần nhất khi viết wrapper hoặc bản triển khai tương thích. Ban đầu nhiều dự án vốn khởi đầu từ tài liệu tham chiếu API nội bộ, và “viết tài liệu” chỉ đơn giản là công khai nó ra bên ngoài. Tham khảo hệ thống tài liệu divio

    • Khái niệm Diátaxis rất tuyệt. Tuy nhiên, để áp dụng vào dự án thực tế thì không hề dễ. Mỗi dự án cần một tỷ lệ tài liệu khác nhau, và việc cung cấp mọi hình thức trong cùng một website là không hiệu quả. Tỷ lệ đó cũng liên tục thay đổi theo mức độ phát triển và chuyên môn của cộng đồng. Tôi ước gì có một cách tiếp cận thực tế hơn. Tài liệu hóa là một bài toán khó, và hy vọng một ngày nào đó sẽ có lời giải tốt hơn. Hiện tại, chất lượng vẫn chủ yếu phụ thuộc vào lượng thời gian và chuyên môn được đầu tư, mà thực tế là thường không đủ

  • Tôi gặp vấn đề này rất thường xuyên ở Unity và Unreal. Đặc biệt là tài liệu về node của Unreal thường chỉ chụp lại screenshot của node và ghi lại tên của nó, chứ hoàn toàn không chỉ ra cách dùng thực tế. Với Unity cũng vậy, nhiều khi tôi tìm tài liệu chỉ để biết cách dùng đúng của một hàm nào đó nhưng lại chẳng có nội dung gì. Nếu có thể, tôi còn muốn tự mình đóng góp ví dụ cho tài liệu Unity

    • Tài liệu tệ của Unreal cũng khiến tôi lãng phí vô số thời gian. Họ có cảm giác như đang theo kiểu “code là tài liệu”, nhưng mấy phần “mô tả screenshot node” cho Blueprint thì thật sự buồn cười

    • Liên quan đến £JOB, tôi thắc mắc khi mọi người viết $job thì đó là theo nghĩa công việc kiếm tiền (task/job) hay chỉ đơn giản là lấy từ tên biến. Đến mức này thì thế giới quan của tôi bắt đầu lung lay

  • Tôi dùng ImageMagick khá thường xuyên, và lúc nào cũng phải lên Google tìm ví dụ. Vì vậy tôi gom các ghi chú cá nhân lại thành một bộ sưu tập nhỏ các ví dụ lệnh. Tôi cũng thêm phần giải thích chi tiết cho từng tham số. Không chỉ có ví dụ như bài blog này, mà tôi nghĩ cần cả phần giải thích đi kèm. Nó vẫn đang ở dạng nháp, nhưng với các tác vụ hằng ngày như resize, tối ưu hóa và layering thì đã cực kỳ hữu ích. Liên kết công khai ghi chú của tôi

  • Ví dụ mã có thể được chạy như unit test để ngăn tài liệu bị cũ hoặc bị hỏng. Đây là lợi thế mà ngôn ngữ tự nhiên không có được

    • Giờ đây khi LLM phát triển hơn, có lẽ cũng sẽ thử được việc kiểm chứng độ chính xác của tài liệu API chẳng hạn

  • Một ý kiến hơi cực đoan: nếu đặc tả của một phương thức cụ thể không thể được suy ra trực quan chỉ từ chữ ký hàm và một vài ví dụ tiêu biểu, thì phương thức đó đang cố làm quá nhiều việc. Tôi cũng không muốn phải học những abstraction ràng buộc chân tay hoặc những ngoại lệ phức tạp

    • Tôi không nghĩ vậy. Ví dụ là cần thiết không chỉ để nói về bản thân phương thức đó, mà còn để cho thấy “nó nên được dùng cùng các phương thức khác như thế nào”. Ngay cả khi có thể suy ra mọi thứ từ chữ ký hàm, bạn vẫn rất dễ bỏ sót những phần quan trọng như cấu hình còn thiếu, bước chuẩn bị hay cách xử lý kết quả. Vì thế ví dụ là thiết yếu
 
howudoin 2025-10-11

Trong hệ Java và văn hóa hướng đối tượng có quá nhiều câu mô tả vô nghĩa và tài liệu mang tính hình thức; các framework thuộc hệ Python, vốn kế thừa bầu không khí đó, cũng đặc biệt nghèo nàn về ví dụ.

Ví dụ về kiểu tài liệu hóa vô nghĩa
add(left, right) - cộng vế trái và vế phải

Trong khi những thứ thực sự quan trọng như kiểu dữ liệu của tham số, các ngoại lệ có thể được trả về, hình dạng của giá trị kết quả hay cấu trúc hoạt động thì lại không được giải thích.

Nếu là kiểu man page của ngôn ngữ C thì chỉ với mô tả ngắn gọn thôi cũng có thể suy ra từ tên hàm và tên tham số để dùng được.