Điều gì có ác cảm với tài liệu trong ngành?

Dường như có ác cảm với việc viết ngay cả những tài liệu cơ bản nhất. READMEs dự án của chúng tôi là tương đối trần. Thậm chí không có danh sách phụ thuộc được cập nhật trong các tài liệu.

Có điều gì đó tôi không biết trong ngành công nghiệp khiến các lập trình viên không thích viết tài liệu? Tôi có thể gõ các đoạn tài liệu nếu cần, vậy tại sao những người khác lại ác cảm với nó?

Quan trọng hơn, làm thế nào để tôi thuyết phục họ rằng viết tài liệu sẽ giúp chúng ta tiết kiệm thời gian và sự thất vọng trong tương lai?

Tôi không nghĩ sẽ hữu ích khi suy đoán về động lực của những người không chấp nhận điều gì đó mà bạn cho là thực hành tốt hoặc những người đang tiếp tục làm điều gì đó mà bạn coi là thực hành tồi. Trong doanh nghiệp này, những người thuộc một hoặc cả hai loại đó sẽ vượt xa những người mà bạn sẽ thấy tận mắt, vì vậy hãy ngừng làm cho mình trở nên điên rồ.

Thay vào đó, tập trung vào vấn đề và giải quyết có thể.

1. Viết tài liệu tốt cho mình

Có thể không thực tế khi hy vọng rằng mọi người trong nhóm của bạn sẽ hướng những nỗ lực của họ vào những điều bạn thấy là một vấn đề. Điều này đặc biệt đúng nếu bạn là người mới tham gia vào nhóm. Tôi mạo hiểm đoán bạn là ai, bởi vì nếu bạn là thành viên sáng lập của đội, có vẻ như bạn đã giải quyết vấn đề này từ rất sớm.

Thay vào đó, hãy xem xét, làm việc hướng tới mục tiêu tự viết tài liệu tốt và khiến mọi người sử dụng nó. Ví dụ: nếu ai đó trong nhóm của tôi hỏi tôi mã nguồn của Dự án A ở đâu hoặc cấu hình đặc biệt mà Dự án A cần, tôi chỉ cho họ đến trang wiki Dự án A.

Nếu ai đó hỏi tôi làm thế nào để viết một bản triển khai mới của Factory F để tùy chỉnh một thứ cho Client C, tôi nói với họ rằng nó ở trang 10 của hướng dẫn dành cho nhà phát triển.

Hầu hết các nhà phát triển ghét đặt câu hỏi có thể khiến họ trông giống như họ không thể "đọc mã" thậm chí nhiều hơn họ ghét đọc tài liệu, vì vậy sau khi trả lời đủ bản chất này, họ sẽ đến tài liệu trước.

2. Chứng minh giá trị của tài liệu của bạn

Hãy chắc chắn rằng bạn tận dụng mọi cơ hội để chỉ ra nơi tài liệu đang chứng minh giá trị của nó (hoặc sẽ có, nếu được sử dụng). Cố gắng tinh tế và tránh "Tôi đã nói với bạn như vậy", nhưng nói những điều như là hoàn toàn hợp pháp

Để tham khảo trong tương lai, trang wiki của dự án này có thông tin về nhánh mã lõi được tạo để hỗ trợ phát hành 2.1, vì vậy trong tương lai chúng ta có thể tránh phải thực hiện kiểm tra hồi quy đầy đủ nếu những người đang duy trì kiểm tra phiên bản phát hành wiki trước khi kiểm tra mã.

hoặc là

Tôi rất vui vì tôi đã viết ra các bước để thực hiện Nhiệm vụ T. Tôi không thực sự quan tâm nếu không có ai sử dụng nó - nó đã giúp tôi tiết kiệm nhiều thời gian hơn so với những gì tôi đã viết.

3. Quản lý trên tàu

Sau một vài sự cố trong đó có tài liệu chứng minh là tiết kiệm thời gian / tiền bạc, có lẽ bạn sẽ nhận thấy một "sự tan băng" riêng biệt đối với tài liệu. Đây là thời điểm để nhấn điểm bằng cách bắt đầu đưa thời gian tài liệu vào các ước tính của bạn (mặc dù thật lòng tôi thường cập nhật / tạo tài liệu trong khi các quy trình dài đang chạy, chẳng hạn như biên dịch hoặc đăng ký). Đặc biệt nếu đây là một lần thuê gần đây, có thể điều này sẽ không bị nghi ngờ, nhưng thay vào đó được xem như là một cách làm mới mà bạn đang mang đến từ nơi làm việc trước đây (có thể là như vậy).

Lời cảnh báo: Hầu hết các ông chủ không muốn khiến mọi người làm bất cứ điều gì, đặc biệt là những thứ không liên quan trực tiếp đến một nhiệm vụ có thể tính hóa đơn, vì vậy đừng hy vọng sự hỗ trợ này sẽ ở dạng ủy thác. Thay vào đó, nó có nhiều khả năng cung cấp cho bạn quyền tương đối tự do để viết nhiều tài liệu hơn.

4. Khuyến khích tài liệu khi bạn nhìn thấy nó

Có lẽ một phần lý do mọi người không viết tài liệu thường xuyên như họ nên họ cảm thấy không ai đọc nó. Vì vậy, khi bạn thấy một cái gì đó bạn thích, hãy chắc chắn ít nhất đề cập rằng bạn rất vui vì nó có sẵn.

Nếu nhóm của bạn thực hiện đánh giá mã, đây là thời gian bạn có thể bỏ vào một hoặc hai từ tinh tế để khuyến khích các bình luận tốt.

Cảm ơn bạn đã ghi lại cách giải quyết cho lỗi B trong Khung G. Tôi không biết về điều đó và tôi không nghĩ rằng tôi có thể hiểu những gì bạn đang làm mà không có điều đó trong đó.

Nếu bạn có ai đó trong nhóm thực sự nhiệt tình với tài liệu, sẽ không hại gì khi nuôi dưỡng người đó thông qua việc đi ăn trưa hoặc cà phê và đảm bảo cung cấp một chút xác nhận để chống lại sự nản lòng mà họ có thể nhận được khi nhìn thấy phần còn lại của nhóm không coi trọng tài liệu nhiều.

Ngoài ra, đó thực sự không phải là vấn đề của bạn trừ khi bạn ở vị trí lãnh đạo hoặc quản lý. Bạn có thể dẫn một con ngựa xuống nước, nhưng bạn không thể làm cho nó uống. Nếu đó không phải là con ngựa của bạn, bạn có thể không vui vì nó khát, nhưng tất cả những gì bạn có thể làm là lấp đầy máng.

Có hai yếu tố chính trong kinh nghiệm của tôi:

Thời hạn

Hầu hết các công ty đều hướng đến việc QA, nợ công nghệ và thiết kế thực tế bị cắt giảm để người quản lý dự án trông không tệ hoặc đạt được một số thời hạn khách hàng quá hứa hẹn vô lý. Trong môi trường này, nơi thậm chí chất lượng chức năng bị cắt giảm, thì một khoản đầu tư dài hạn như tài liệu có rất ít cơ hội.

Thay đổi

Một thực tiễn tốt nhất tương đối mới cho các nhà phát triển là không nhấn mạnh ý kiến. Ý tưởng là việc giữ thông tin ở hai nơi (mã [bao gồm các bài kiểm tra] và các nhận xét xung quanh mã) dẫn đến rất nhiều chi phí trong việc giữ chúng đồng bộ hóa để có ít lợi ích. "Nếu mã của bạn khó đọc đến mức bạn cần bình luận, liệu có tốt hơn thời gian để làm sạch mã không?"

Cá nhân tôi thậm chí sẽ không nhìn vào bình luận nữa. Mã không thể nói dối.

Tài liệu theo cùng một tĩnh mạch. Với việc áp dụng rộng rãi nhanh nhẹn, mọi người thừa nhận rằng các yêu cầu thay đổi thường xuyên. Với việc sử dụng rộng rãi tái cấu trúc, việc tổ chức mã sẽ thay đổi đáng kể. Tại sao phải dành thời gian ghi lại tất cả những thứ này bị ràng buộc phải thay đổi? Mã và kiểm tra nên làm một công việc đủ tốt làm điều đó.

Có một số yếu tố chơi ở đây:

1. Mã được viết tốt là tài liệu riêng của nó. Tất cả những thứ khác đều bằng nhau, tốt hơn là viết mã rõ ràng hơn nói cho chính nó, hơn là nhiều tài liệu hơn. Làm điều đó và bạn sẽ cần sửa đổi ít tài liệu hơn khi bạn thay đổi mã đó.

2. Viết tài liệu được cho là một kỹ năng khác với viết mã. Một số nhà phát triển phần mềm giỏi hơn nó. Một số tốt hơn nhiều trong việc viết mã so với họ đang viết tài liệu.

3. Tài liệu chỉ nên được viết một lần , không phải hai lần (một lần trong mã nguồn và một lần nữa trong hướng dẫn của lập trình viên). Đó là lý do tại sao chúng ta có những thứ như các trình tạo tài liệu và nhận xét XML. Thật không may, sử dụng các công cụ như vậy có thể khó khăn và cồng kềnh hơn là chỉ viết tài liệu bằng tay, đó là lý do tại sao bạn không thấy những công cụ đó được sử dụng rộng rãi.

4. Tài liệu tốt là tốn thời gian, và khó để làm tốt. Tất cả những thứ khác đều bằng nhau, có thể có nhiều giá trị hơn để viết mã mới hơn là viết tài liệu cho mã đã tồn tại.

5. Khi mã thay đổi, bạn cũng phải thay đổi tài liệu. Càng ít tài liệu, càng ít phải thay đổi.

6. Không ai đọc tài liệu nào, vậy tại sao phải bận tâm?

Voi trong phòng: Lập trình viên không (nhất thiết) là nhà văn. Họ cũng không nhất thiết phải có khả năng làm sáng tỏ việc triển khai của họ cho các nhà văn kỹ thuật. Con voi thứ hai trong phòng: Các nhà văn kỹ thuật thường không thể đưa ra các chi tiết hữu ích cho các nhà phát triển trong tương lai (ngay cả khi các nhà phát triển sẽ từ chối giải thích cho họ).

Một hệ thống phức tạp có thể trở nên gần khó hiểu theo thời gian mà không có tài liệu phù hợp. Mã trở nên ít có giá trị tỷ lệ nghịch với khả năng xem xét kỹ lưỡng của nó [sic]. Đã giải quyết, ban quản lý thuê Kỹ sư phần mềm, người có thể đọc mã và dỗ chi tiết từ các nhà phát triển, trả tiền cho anh ta theo tỷ lệ của nhà phát triển và bắt buộc anh ta phải lập tài liệu và duy trì tài liệu. Người viết bài này có thể đọc mã và sẽ biết những câu hỏi cần hỏi và sẽ điền chi tiết khi cần thiết. Giống như bạn có một bộ phận QA, bạn có một bộ phận tài liệu nội bộ.

Mã sẽ trở nên có giá trị hơn, vì bạn có thể cấp phép cho bên thứ 3 (vì anh ta có thể hiểu được mã này), mã có thể được kiểm tra và cải thiện / tái xác nhận dễ dàng hơn, bạn sẽ sử dụng lại mã tốt hơn ngay cả khi bạn có thể dễ dàng sử dụng mã đưa ra các phiên bản nhẹ hơn của phần mềm và bạn sẽ có thể giới thiệu các nhà phát triển mới dễ dàng hơn vào dự án, các kỹ sư hỗ trợ của bạn sẽ thích làm việc cho bạn.

Điều này sẽ không bao giờ xảy ra.

Quan trọng hơn, làm thế nào để tôi thuyết phục họ rằng viết tài liệu sẽ giúp chúng ta tiết kiệm thời gian và sự thất vọng trong tương lai?

Nó làm điều đó?

Có hai loại tài liệu:

Tài liệu hữu ích

Tài liệu về cách sử dụng thành phẩm, API, địa chỉ IP hoặc tên URL mà máy chủ của chúng tôi có, v.v. Về cơ bản, mọi thứ được sử dụng nhiều và hàng ngày. Thông tin sai sẽ được phát hiện nhanh chóng và sẽ được sửa chữa. Cần tìm thấy dễ dàng và dễ dàng để chỉnh sửa (ví dụ Wiki trực tuyến).

Tài liệu vô dụng

Tài liệu thay đổi thường xuyên, rất ít người quan tâm đến nó và không ai biết tìm nó ở đâu. Giống như trạng thái hiện tại của một tính năng đang được thực hiện. Hoặc các tài liệu yêu cầu trong tài liệu word ẩn ở đâu đó trong SVN, được cập nhật 3 năm trước. Tài liệu này sẽ mất thời gian để viết và thời gian để phát hiện ra rằng nó sai sau này. Bạn không thể dựa vào loại tài liệu này. Nó vô dụng. Nó lãng phí thời gian.

Các lập trình viên không muốn viết hoặc đọc tài liệu vô dụng. Nhưng nếu bạn có thể chỉ cho họ tài liệu hữu ích, họ sẽ viết nó. Chúng tôi đã thành công với nó trong dự án cuối cùng của tôi khi giới thiệu một Wiki nơi chúng tôi có thể viết tất cả thông tin mà chúng tôi cần thường xuyên.

Tôi muốn nói rằng lý do chính là thiếu ý chí và thiếu hiểu biết về chức năng của tài liệu. Có một số loại tài liệu để xem xét:

Tài liệu sản phẩm / phát hành

Đây là bất cứ điều gì đi ra ngoài với sản phẩm 'hoàn thành' của bạn. Đây không chỉ là hướng dẫn sử dụng, đây là READMEs, Nhật ký thay đổi, CÁCH THỨC và tương tự. Về lý thuyết, bạn có thể thoát khỏi việc không viết những thứ này, nhưng bạn kết thúc với một sản phẩm mà mọi người không muốn sử dụng hoặc một gánh nặng hỗ trợ đắt đỏ không cần thiết.

Tài liệu API

Điều này mô tả một cái gì đó nên tương đối tĩnh. Vì nhiều người tiêu dùng có thể đang mã hóa API của bạn, nên nó đủ ổn định đủ để một số văn xuôi mô tả cách sử dụng nó có giá trị. Mô tả các tham số nào được hỗ trợ, giá trị trả về có thể là gì và lỗi nào có thể được đưa ra sẽ cho phép người dùng khác có thể hiểu API của bạn ở mức độ trừu tượng phù hợp - giao diện ( không phải là triển khai).

Mã nhận xét

Hiện tại, ý kiến ​​của ngành về ý kiến ​​dường như đang thay đổi. Khi tôi lần đầu tiên bắt đầu viết mã một cách chuyên nghiệp, các bình luận là một điều kiện thiết yếu khi viết mã. Bây giờ, thời trang là viết mã rất rõ ràng, bình luận là không cần thiết. Tôi muốn đoán rằng điều này một phần là do thực tế là nhiều ngôn ngữ hiện đại được viết ở cấp độ cao hơn nhiều và việc viết mã dễ đọc bằng Java, JavaScript, Ruby, v.v. dễ dàng hơn so với trình biên dịch , C, FORTRAN, v.v ... Do đó, các bình luận có giá trị lớn hơn nhiều.

Tôi vẫn tin rằng có giá trị trong các nhận xét mô tả ý định của một phần của mã hoặc một số chi tiết về lý do tại sao một thuật toán nhất định được chọn trên một thuật toán rõ ràng hơn (để tránh các kẻ thù tái cấu trúc quá nhiệt tình khỏi 'sửa lỗi' mã không ' t thực sự cần phải được sửa chữa).

Thật không may, có rất nhiều sự ích kỷ, hợp lý hóa và tự ảo tưởng liên quan đến quyết định không lập trình của các lập trình viên. Thực tế là, giống như mã, đối tượng chính cho tài liệu là những người khác. Do đó, các quyết định viết (hoặc không viết) tài liệu, ở bất kỳ cấp độ nào, là một quyết định nên được đưa ra ở cấp độ nhóm. Đối với các mức độ trừu tượng cao hơn, có thể có ý nghĩa hơn khi có ai đó, ngoài các nhà phát triển, thực hiện nó. Đối với tài liệu ở cấp độ bình luận, việc đạt được thỏa thuận về mục đích và mục đích của các bình luận nên được thống nhất với nhau, đặc biệt là trong các nhóm có khả năng và kinh nghiệm hỗn hợp. Thật không tốt khi có các nhà phát triển cấp cao viết mã mà các nhà phát triển cơ sở không thể tiếp cận. Một số tài liệu được đặt tốt và được viết tốt có thể cho phép một nhóm hoạt động hiệu quả hơn nhiều

Đây là hai xu của tôi.

1. Tuyên ngôn Agile tuyên bố "Phần mềm làm việc trên tài liệu toàn diện" và không phải ai cũng đọc để tiếp cận "Nghĩa là, trong khi có giá trị ở các mục bên phải, chúng tôi đánh giá các mục ở bên trái nhiều hơn".

2. Đáng buồn thay, nó phổ biến đối với https://en.wikipedia.org/wiki/Code_and_fix và tài liệu không hoạt động với mô hình này (Nó không đồng bộ).

3. Công nghiệp phát triển phần mềm không được quy định tốt. Không có yêu cầu pháp lý để viết tài liệu.

4. Mã tự viết tài liệu là xu hướng hiện nay.

Phải nói rằng, tôi nghĩ rằng có rất nhiều tài liệu tốt ngoài đó.

Tài liệu cần có thời gian và tôi nghi ngờ rất nhiều nhà phát triển đã có quá nhiều cuộc chạy đua với tài liệu tồi tệ hơn vô dụng. Họ có ý tưởng rằng không chỉ tài liệu sẽ gây rắc rối cho họ từ người quản lý của họ (cùng một người luôn cắt phần QA trong lịch trình), nhưng nó sẽ không giúp được ai, kể cả họ.

Bất kỳ một chút tài liệu nào là một khoản đầu tư trong tương lai. Nếu bạn không quan tâm đến tương lai (vì bạn không nghĩ vượt quá mức lương tiếp theo hoặc vì bạn nghĩ đó sẽ không phải là vấn đề của bạn), thì suy nghĩ về việc làm tài liệu là vô cùng đau đớn.

Nhiều câu trả lời khác nhấn mạnh rằng có ít nhất hai loại tài liệu: một bộ cho các nhà phát triển khác và một bộ khác cho người dùng cuối. Tùy thuộc vào môi trường của bạn, bạn cũng có thể cần tài liệu bổ sung cho quản trị viên hệ thống, người cài đặt và nhân viên trợ giúp. Mỗi đối tượng mục tiêu có nhu cầu và mức độ hiểu biết khác nhau.

Hãy xem xét nhà phát triển điển hình (stereo-): Anh ấy là một lập trình viên theo sự lựa chọn. Anh ấy đã chọn một sự nghiệp ngoài tầm mắt công chúng và dành nhiều giờ sau bàn phím giao tiếp chủ yếu với chính mình. Quá trình tài liệu là một hình thức giao tiếp và bộ kỹ năng cần thiết để tạo ra tài liệu tốt là phản đối với các kỹ năng cần thiết để tạo ra mã tốt.

Một người viết tài liệu tốt có thể giao tiếp bằng nhiều ngôn ngữ: ngôn ngữ của người dùng, ngôn ngữ quản lý, ngôn ngữ của nhân viên hỗ trợ, ngôn ngữ của các nhà phát triển. Công việc của một người viết tài liệu là hiểu những gì một lập trình viên truyền đạt và dịch nó thành một hình thức mà tất cả các nhóm khác có thể hiểu được.

Khi bạn mong đợi các lập trình viên phát triển kỹ năng cần thiết để trở thành người giao tiếp giỏi (bằng văn bản hoặc bằng cách khác), lượng thời gian dành cho việc mài giũa bộ kỹ năng chính (mã hóa!) Sẽ giảm. Càng đi xa khỏi vùng thoải mái của mình (mã hóa và giao tiếp với các lập trình viên khác), thì càng cần nhiều thời gian và năng lượng để thực hiện tốt nhiệm vụ. Bạn có thể mong đợi một cách hợp lý một lập trình viên chuyên nghiệp mong muốn tập trung chủ yếu vào các năng lực cốt lõi của anh ta, với chi phí của tất cả những người khác.

Vì lý do này, tài liệu (ngoại trừ nhận xét mã nội tuyến) là tốt nhất để lại cho các nhà truyền thông, không phải là lập trình viên.

Đọc mã cho bạn thấy làm thế nào nó hoạt động. Nó không thể giải thích tại sao : bạn cần bình luận.

Đọc mã cho bạn thấy tên của một phương thức và các loại tham số. Nó không thể giải thích ngữ nghĩa, hoặc ý định chính xác của tác giả: bạn cần bình luận.

Nhận xét không thay thế đọc mã, họ thêm vào nó.

Tài liệu không được thực thi như mã. Kết quả là thường không có các vòng phản hồi hiệu quả để xác minh rằng tài liệu đã được đưa ra và hoàn tất. Đây là cùng một lý do mà các bình luận mã có xu hướng thối.

Donald Knuth đã thúc đẩy Lập trình Văn học như một cách để cải thiện chất lượng phần mềm, viết tài liệu bằng mã hiệu quả. Tôi đã thấy một vài dự án đã sử dụng phương pháp này khá hiệu quả.

Cá nhân tôi cố gắng theo xu hướng hiện đại là giữ API công khai của mã của bạn càng dễ đọc càng tốt và sử dụng các bài kiểm tra đơn vị để sử dụng tài liệu cho các nhà phát triển khác. Tôi nghĩ rằng đây là một phần trong ý tưởng lớn hơn về việc API của bạn có dạng có thể được khám phá và khám phá. Tôi nghĩ cách tiếp cận này là một phần của những gì HATEOAS cố gắng đạt được với các dịch vụ web.

Một điểm nhỏ, nhưng một điểm có vẻ quan trọng với một số nhà phát triển viết tài liệu ít đáng ghét: họ không thể gõ. Nếu bạn có một số xấp xỉ của hệ thống 10 ngón tay, bạn có xu hướng viết thêm tài liệu chỉ vì nó dễ dàng. Nhưng nếu bạn bị mắc kẹt với việc săn bắn và mổ bạn sẽ bị lạc. Nếu tôi chịu trách nhiệm tuyển dụng thì đây thực sự là thứ tôi sẽ kiểm tra.

Những người không thích đọc tài liệu không thích viết tài liệu. Rất nhiều lập trình viên sẽ làm tất cả những gì có thể để tránh đọc tài liệu kỹ lưỡng.

Đừng tập trung vào văn bản, tập trung vào việc đọc. Khi các lập trình viên đọc tài liệu và đồng hóa mọi thứ từ nó, họ sẽ thấy giá trị và có xu hướng viết nhiều hơn.

Khi tôi bắt đầu công việc hiện tại của mình và tiếp quản một dự án phần cứng + phần mềm từ những người trước đây đã làm việc với nó, tôi đã nhận được một tài liệu từ một trăm trang mô tả hệ thống. Phải mất nhiều ngày để sản xuất. Tôi nhìn nó có thể hai lần. Mặc dù có lượng thông tin khổng lồ trong đó, nhưng nó hiếm khi trả lời các câu hỏi thực tế mà tôi có về hệ thống, và ngay cả khi có, nó vẫn nhanh hơn để xem mã.

Sau khi đủ kinh nghiệm như thế, bạn mới bắt đầu suy nghĩ, tại sao phải bận tâm? Tại sao dành thời gian của bạn để trả lời các câu hỏi mà mọi người không bao giờ hỏi? Bạn bắt đầu nhận ra mức độ khó thực sự của việc dự đoán những thông tin mà mọi người sẽ tìm kiếm trong tài liệu; nó chắc chắn chứa đầy những sự thật hóa ra là vô dụng, không rõ ràng hoặc không rõ ràng và thiếu câu trả lời cho những câu hỏi cấp bách nhất. Hãy nhớ rằng, sản xuất tài liệu hữu ích là một nỗ lực trong việc dự đoán hành vi của con người. Giống như một thiết kế giao diện người dùng khó có thể thành công trước khi nó trải qua nhiều lần thử nghiệm và gỡ lỗi, nên thật ngây thơ khi nghĩ rằng có thể viết tài liệu hữu ích chỉ dựa trên mong đợi về cách mọi người sẽ diễn giải hệ thống và những gì vai trò của tài liệu và ngôn ngữ của nó sẽ đóng vai trò giải thích đó.

Tôi có xu hướng nghĩ rằng hầu hết áp lực để viết tài liệu bắt nguồn từ thực tế rằng đó là một việc vặt khó chịu và mọi người như cảm thấy tội lỗi với nhau khi làm những việc lặt vặt khó chịu ("Bạn đã không ăn miếng dán filboid của bạn!").

TUY NHIÊN

Tôi không nghĩ rằng tài liệu này, theo mọi cách, là vô vọng. Tôi nghĩ rằng điều đó là vô vọng khi mọi người nhìn vào tài liệu vì gánh nặng thêm này phải được hoàn thành trước khi công việc kết thúc, vì một chút công việc dọn dẹp cuối cùng phải được thực hiện, và như một chiếc hộp cần kiểm tra. Tài liệu là một cái gì đó bạn nên làm việc trong các khía cạnh của ngày mà bạn luôn luôn làm. Tôi nghĩ rằng email là một cách đặc biệt tốt để làm tài liệu. Khi bạn thêm một tính năng mới, hãy viết cho một vài người một email nhanh chóng nói nó là gì. Khi vẽ sơ đồ mới, tạo tệp PDF và gửi cho bất kỳ ai có thể quan tâm. Ưu điểm của email là:

1. Mọi người thường kiểm tra email, trong khi không ai lội qua thư mục có tên "doc".

2. Email tồn tại trong ngữ cảnh, được bao quanh bởi các email khác thảo luận về tính năng và các tính năng liên quan và bất kỳ điều gì khác đang diễn ra vào thời điểm đó.

3. Email ngắn và tập trung và có một dòng chủ đề.

4. Email cho phép những người quan tâm đặt câu hỏi ngay lập tức,

5. Email rất có thể tìm kiếm, bởi vì mọi người sử dụng nó cho tất cả mọi thứ và ứng dụng thư khách đã tiến bộ khá nhiều trong những năm qua.

6. Nếu trong email, ít nhất một người khác sẽ biết tìm nó ở đâu.

Về lý thuyết, dường như các bình luận trong mã cũng phải là "các khía cạnh trong ngày của bạn mà bạn luôn luôn làm", nhưng thành thật mà nói, tôi không bao giờ đọc các bình luận trong mã. Tôi không chắc tại sao, nhưng chúng không hữu ích lắm, có lẽ vì thiếu ngữ cảnh, email sẽ giải quyết được.