Những gì bạn nên để lại cho người kế nhiệm của bạn?

Giả sử rằng bạn là nhà phát triển duy nhất rời bỏ công việc. Những loại thông tin / tài liệu, bên ngoài mã, bạn nên tạo và để lại phía sau để thay thế?

Một câu trả lời rõ ràng là "bất cứ điều gì bạn muốn ở một công việc mới" chắc chắn, nhưng đã được một thời gian kể từ khi tôi bắt đầu một công việc mới, và tôi quên mất những điều quan trọng nhất mà tôi cần lúc đó là gì.

Tôi đang nghĩ:

• tài khoản / mật khẩu
• vị trí của thiết bị, sao lưu, đĩa CD phần mềm

Còn gì nữa không

• Tài khoản & mật khẩu
• Thông tin máy chủ
• Mã tốt
• Tài liệu
  • Sơ đồ và giải thích cơ sở dữ liệu là tuyệt vời
  • Danh sách các số lẻ trong mã
• Thủ tục
• Giải thích các quy trình thủ công, hoặc thỉnh thoảng, không rõ ràng, làm việc
• Danh sách các chương trình họ đã sử dụng hoặc thấy hữu ích
• Thông tin liên lạc ;)

Một tách cà phê mạnh mẽ và một lời xin lỗi.

Là những gì tôi ước tôi còn lại.

• Tài liệu. Làm thế nào là khó để viết một vài bình luận? Xây dựng ghi chú, ghi chú triển khai, di chuyển các ghi chú hệ thống. Phải làm gì khi bạn khởi động lại và mọi thứ đã biến mất.
• Giấy tờ. Viết ra lý do tại sao nó được thực hiện theo cách này để tôi không phải thắc mắc tại sao bạn không làm theo cách khác. Hệ thống sao lưu hoạt động như thế nào, máy chủ phản ứng thế nào với tải, kiểm tra, trường hợp kiểm thử, trường hợp sử dụng.
• Ghi chú. "Khi sử dụng cơ sở dữ liệu, đừng bao giờ nói SELECT * FROM clients. Chúng tôi không chắc tại sao nhưng nó lại hủy cơ sở dữ liệu" .

Địa chỉ email của tôi, hoặc thậm chí số điện thoại.

Theo kinh nghiệm của tôi, thật khó để viết từng chi tiết, vì vậy điều tốt nhất là có sẵn (ở một mức độ nhất định) nếu người kế nhiệm của bạn cần thêm thông tin.

Tài liệu về các chương trình bạn đã viết, ví dụ như mục đích của chúng, vị trí của các tệp nguồn để phát triển trong tương lai, mật khẩu, v.v.

Điều này có thể là trong mã dưới dạng một nhận xét hoặc bên ngoài trong tầm nhìn rõ ràng.

Không chỉ là tài liệu, tôi muốn biết tại sao một số quyết định được đưa ra khi chúng được đưa ra. Chúng tôi hiện đang sử dụng SWIG trên một dự án và một trong những nhà phát triển khác muốn biết lý do tại sao chúng tôi không sử dụng Boost :: Python. Câu trả lời đơn giản là khách hàng không cho phép sử dụng Boost tại thời điểm đó. Bây giờ là một câu chuyện khác nhau.

Những điều như vậy sẽ giúp họ không chỉ trong việc hiểu dự án mà còn những hạn chế / hạn chế / thách thức thực hiện của bạn đã vượt qua. Nó sẽ cung cấp cho họ một điểm khởi đầu để bảo trì trong tương lai và tăng cường tính năng.

Một điều tôi không thấy ai khác đề cập (mặc dù tôi có thể đã bỏ qua nó) là ghi lại cách thiết lập môi trường dev. Tôi nhận ra rằng hầu hết thời gian nó chỉ cần cài đặt một vài thứ, nhận bản mới nhất, biên dịch và bạn đã hoàn tất. Tuy nhiên, đôi khi còn nhiều điều hơn thế (SharePoint là một tình huống xuất hiện trong tâm trí) và ghi lại những gì tụ điện thông lượng phải được cấu hình theo cách nào sẽ rất hữu ích cho linh hồn tội nghiệp theo bạn.

Nếu là chương trình máy tính để bàn, cách xây dựng toàn bộ hệ thống từ đầu (có thể là một số chương trình riêng biệt), cách tạo gói để phân phối (phụ thuộc vào phiên bản .NET) và cách triển khai nó đến máy chủ để tải xuống nếu có thể, hoặc ghi nó vào đĩa CD hoặc DVD.

Nếu đó là chương trình dựa trên web, FTP và (nếu có thể) truy cập SSH vào máy chủ và công cụ nào được sử dụng để tạo và kiểm tra mã cục bộ.

Nếu là hệ thống nhúng, hãy hoàn thành các hướng dẫn về cách xây dựng hình ảnh nhị phân, công cụ nào được sử dụng, cách tải xuống và flash mã vào sản phẩm, cách thiết lập hệ thống tệp trên thiết bị, nếu có.

Gần đây tôi đã rời bỏ một công việc có hoàn cảnh tương tự với bạn (Tôi không phải là nhà phát triển duy nhất , nhưng thực sự chỉ có hai chúng tôi, vì vậy tôi có khá nhiều kiến ​​thức mà anh chàng kia không có (và ngược lại, tất nhiên)).

Về mặt tài liệu thông thường, điều quan trọng là ghi lại tổng quan về toàn bộ hệ thống. Các thành phần riêng lẻ đã được ghi lại trong mã, nhưng sự tương tác giữa các thành phần và lý do tại sao điều này hoặc tại sao điều này cần nói chuyện với thành phần đó lại quan trọng và không phải lúc nào cũng dễ dàng tìm ra chỉ bằng cách gỡ lỗi / nhìn vào mã.

Sau đó, khoảng một tháng trước khi tôi rời đi, mỗi lần tôi làm điều gì đó mà chỉ tôi có thể làm, tôi đã viết ra chính xác những gì đã xảy ra, những gì tôi phải làm và tại sao. Đây thường là một trường hợp "có lỗi trong thành phần xyz, để sửa nó tôi biết phải tìm trong tập tin abc vì X, sau đó tôi phải làm cái này, cái này và cái này".

Tất nhiên, tôi đã để lại địa chỉ email và số điện thoại của mình trong trường hợp có bất cứ điều gì xảy ra mà họ không thể tự mình tìm ra. Tôi đã nhận được một vài cuộc gọi trong vài tuần đầu tiên, nhưng chúng dần dần bỏ đi.

Tất cả chúng ta đều muốn một sơ đồ luồng dữ liệu hoàn chỉnh của hệ thống với một danh sách các yêu cầu chức năng. Nhiều khả năng bạn không bao giờ có được điều đó khi bạn viết hệ thống ở vị trí đầu tiên! Giống như hầu hết các nơi, tài liệu tốt nhất có lẽ là chính mã, vì vậy điều tôi thích nhất là mã tài liệu tốt. Dòng và dòng ý kiến ​​trong mã giải thích những gì bạn đang cố gắng làm cả về mặt kỹ thuật và chức năng.

Quy tắc số 1 cho tài liệu không phải là những gì nó làm mà là tại sao . Điều gì là nền tảng cho các chương trình chạy, và họ làm gì?

Tôi nghĩ những gì tôi muốn thấy trong các tài liệu bên cạnh thông thường sẽ là những tính năng bị bỏ lại. Giống như tại sao một số ý tưởng nhất định KHÔNG được thực hiện hoặc một nền tảng hoặc phương pháp nhất định KHÔNG được sử dụng (đó là một lựa chọn rõ ràng).

Điều này đảm bảo rằng người kế nhiệm luôn biết không nên làm gì hoặc nếu anh ta có khả năng hơn thì có lẽ anh ta có thể đưa ra một công việc xung quanh và làm cho các tính năng nhất định hoạt động.

Điều này đặc biệt áp dụng cho các dự án nguồn mở. Có thể tiết kiệm rất nhiều thời gian và sức mạnh não!