Tại sao nhiều thư viện không có / tài liệu kém? [đóng cửa]

Theo cách tương tự như Làm thế nào các dự án nguồn mở có thể thành công mà không cần tài liệu về thiết kế hoặc kiến ​​trúc của chúng? Câu hỏi, tôi tò mò: Tại sao rất nhiều thư viện thiếu tài liệu người dùng cuối?

Quan điểm của tôi là thế này:

1. Hầu hết mọi người đều đồng ý rằng đọc mã nguồn khó hơn viết mã nguồn.
2. Không có tài liệu, người ta phải đọc mã nguồn của thư viện để sử dụng thư viện đó.
3. Do đó, sử dụng thư viện không có giấy tờ là công việc nhiều hơn là chỉ tạo lại thư viện từ đầu.
4. Kết quả là, nếu bạn muốn mọi người sử dụng thư viện của mình, tốt hơn hết là hãy đảm bảo rằng nó được ghi lại.

Tôi biết nhiều nhà phát triển không thích viết tài liệu và tôi đồng ý rằng đây có thể là công việc tẻ nhạt. Nhưng đó là công việc thiết yếu. Tôi thậm chí còn nói rằng điều quan trọng hơn là một thư viện có tài liệu tốt hơn là có giao diện lập trình viên tốt nhất trên thế giới. (Mọi người sử dụng các thư viện shitty mọi lúc; ít người sử dụng các thư viện không có giấy tờ)

Ồ, lưu ý rằng khi tôi nói tài liệu, tôi có nghĩa là tài liệu thực sự. Không phải nồi hơi Sand lâu đài / Javadoc / Doxygen.

Tôi nghĩ rằng bạn chủ yếu đã trả lời câu hỏi của riêng bạn: bởi vì trong hầu hết các trường hợp, các nhà phát triển sẽ không bận tâm. Vấn đề đặc biệt phổ biến trong các dự án tình nguyện.

Tôi nghĩ rằng có một vấn đề lớn khác: trong nhiều trường hợp, các nhà phát triển đã không thực sự phát triển một mô hình tổng thể về cách thư viện của họ hoạt động (hoặc chỉ gặp khó khăn khi nói rõ mô hình đó). Thật không may, khớp nối mô hình đó và cách các phần của phần mềm khớp với nhau thường là phần quan trọng nhất của tài liệu.

Trong một trường hợp điển hình, những gì được viết có một cái nhìn tổng quan ở mức rất cao ("Đây là một thư viện để làm những thứ tuyệt vời!") Và sau đó là một mô tả cấp độ rất thấp (loại và mô tả của từng tham số được truyền cho từng chức năng). Thật không may, hiếm khi có một mức độ trung gian về lý thuyết chung về cách mọi thứ hoạt động, cách các phần khớp với nhau, v.v ... Phần lớn điều này quay trở lại thực tế là các nhà phát triển thường không cố gắng hình thành, hợp lý hóa hoặc hiểu chúng mã ở mức độ cụ thể của chi tiết. Ít nhất trong một số trường hợp tôi đã thấy, các nhà phát triển được yêu cầu viết tài liệu ở cấp đó thấy nó khá có vấn đề - đến mức nhiều người muốn viết lại mã để nó có tổ chức hơn và dễ giải thích hơn ở cấp độ đó chi tiết.

Viết tốt ở mức độ trừu tượng đó thường rất khó - và nếu nhà phát triển không thực sự nghĩ về nó ở mức độ trừu tượng đó, họ sẽ thường thấy mã hơi xấu hổ và có thể muốn viết lại trước khi họ hài lòng về việc phát hành nó

Tôi nghĩ đôi khi bởi vì nhà phát triển đã gói gọn trong mã đến mức nó "rõ ràng" đối với anh ấy / cô ấy hoạt động như thế nào và họ không thể hiểu tại sao nó lại không rõ ràng với bất kỳ ai khác. Tương tự, vô số trang web sản phẩm cho biết sản phẩm của họ tuyệt vời như thế nào, nhưng thực tế không cho bạn biết nó làm gì!

Bạn tự chỉ ra câu trả lời:

Tôi biết nhiều nhà phát triển không thích viết tài liệu và tôi đồng ý rằng đây có thể là công việc tẻ nhạt.

Là lập trình viên, chúng tôi thích viết mã, nhưng rất ít người trong chúng tôi cũng thích viết tài liệu.

Mặc dù bất kỳ lập trình viên giỏi nào cũng biết giá trị của tài liệu tốt, nhưng cũng cần một khoảng thời gian hợp lý để thực hiện đúng. Vì nó không thú vị và mất nhiều thời gian, nó được đưa vào đống "để làm sau" để nó không bao giờ được thực hiện ở mức thỏa đáng.

Một lưu ý phụ, rất khó để lập trình viên viết tài liệu về sản phẩm của chính họ. Khi họ biết hệ thống rất tốt, một số điều rõ ràng đối với họ. Những phần này thường không bao giờ được đề cập mặc dù không rõ ràng đối với người tiêu dùng.

Viết tài liệu là một kỹ năng. Giống như tất cả các kỹ năng cần có thực hành. Thời gian và công sức chúng tôi dành để viết mã đã được đền đáp ngay lập tức. Chúng ta có thể thấy tính năng mới, lỗi cố định, tốc độ được cải thiện. Viết tài liệu có một khoản tiền chậm trễ. Về lâu dài, nó giúp ích cho những người mới cần làm việc với mã hoặc nếu chúng tôi quay lại làm việc với mã tháng hoặc năm sau. Nó chỉ là tự nhiên chúng tôi tập trung vào ngắn hạn.

Theo tôi, khả năng viết tài liệu tốt là một trong những đặc điểm chính giúp phân biệt các lập trình viên vĩ đại với các lập trình viên tầm thường.

Người có trình độ tốt nhất để viết tài liệu cũng là người có ít động lực nhất để làm việc đó:

anh ấy (hoặc cô ấy) là:

• chủ yếu là người duy trì thư viện, chứ không phải là người dùng. Vì vậy, thư viện càng nhỏ và đơn giản, công việc của anh ta càng dễ dàng. Duy trì một nửa cuốn tiểu thuyết ngoài mã chỉ làm cho công việc của anh ta khó khăn hơn,
• anh ta biết thư viện từ trong ra ngoài, vì vậy anh ta không cần tài liệu,
• Anh ấy là một lập trình viên, anh ấy muốn viết mã, không phải tài liệu.

Tôi không thể nghĩ về bất cứ ai ít đi "Hmm, tôi thực sự nên dành vài giờ để viết một số tài liệu thích hợp cho việc này". Tại sao anh?

Và tất nhiên, có lẽ không có ích gì khi có huyền thoại đô thị này xoay quanh những bình luận kiểu doxygen tự phát là tất cả những gì bạn cần về mặt tài liệu.

Vì vậy, ngay cả trong những trường hợp hiếm hoi mà nhà phát triển thực sự sẵn sàng viết tài liệu, có khả năng 50/50 nhà phát triển đã bị giáo phái này tẩy não khi nghĩ rằng tất cả những gì cần thiết là điền vào một vài bình luận như vậy, nói với bạn những viên đá quý như rằng "hàm Foo getFoo()trả về một đối tượng thuộc loại Foo và nó được sử dụng để lấy đối tượng Foo".

Tài liệu? Chúng tôi không cần tài liệu của stinkin!

Tôi biết cách mã hoạt động, vậy tại sao tôi lại dành thời gian làm tài liệu cho mã của mình? Bên cạnh đó, tôi phải hoàn thành dự án này vào thứ Sáu và tôi sẽ không thực hiện được vì nó là ...