Tôi đã hoàn thành một ứng dụng web về cơ bản được phát triển bằng PHP và chỉ là một ứng dụng web thông thường khác. Thông thường khi tôi cung cấp bản phát hành sản xuất cuối cùng, tôi chỉ bàn giao tài liệu mã và thông tin kiến ​​trúc cho khách hàng. Tuy nhiên, đối với dự án cụ thể này, khách hàng khăng khăng đòi có đầy đủ dữ liệu vào và ra về dự án.

Vì vậy, tôi chỉ tự hỏi ... các tài liệu kỹ thuật và phi kỹ thuật bắt buộc mà tôi có thể cung cấp cho khách hàng của mình ngoài các tài liệu về mã và kiến ​​trúc là gì?

(Ngoài ra, sẽ rất tuyệt khi đánh cho khách hàng về các số liệu thống kê và dữ liệu khác nhau về dự án để anh ta thực sự biết số lượng công việc liên quan và mức độ tuyệt vời của sản phẩm.)

Tôi nghĩ rằng danh sách nên bao gồm:

• Các yêu cầu phi kỹ thuật (đã có một tài liệu như vậy, phải không?)
• Các yêu cầu kỹ thuật
• Một tài liệu "quyết định" (nếu có) quyết định lý do tại sao một số quyết định được đưa ra so với các quyết định khác. Điều này có thể đã có trong một tài liệu kiến ​​trúc hoặc yêu cầu khác, nhưng chúng tôi thường làm điều này một cách riêng biệt cho các Quyết định lớn.
• Mã và các tài nguyên khác (tệp hình ảnh, CSS, v.v ...)
• Mô hình cơ sở dữ liệu (dưới dạng sơ đồ, tài liệu, bất cứ điều gì)
• DDL để tạo cơ sở dữ liệu.
• DML để gieo cơ sở dữ liệu.
• Một tài liệu giải thích thiết lập ứng dụng và xử lý sự cố cơ bản.
• Danh sách bất kỳ tên người dùng quan trọng và mật khẩu của họ (đối với tài khoản Quản trị viên), cũng như hướng dẫn về cách thay đổi mật khẩu. Lý tưởng nhất là khi họ thiết lập trang web lần đầu tiên, họ sẽ được nhắc nhập mật khẩu quản trị viên mới, nhưng đây là một kiến ​​trúc nhiều hơn.
• Yêu cầu hệ thống và đối với các ứng dụng web cũng yêu cầu lưu trữ tối thiểu (Ứng dụng có cần MySQL hoặc PostgreQuery không? RAM bao nhiêu ?, V.v ...)

Không phải tất cả những điều này có thể có sẵn (hoặc cần thiết) cho mọi dự án, nhưng tôi nghĩ đây là một hướng dẫn chung tốt.

Ngoài câu trả lời thực sự hay của FrustratedWithFormsDesigner tôi muốn nói những gì các tài liệu phi kỹ thuật bao gồm (như chúng tôi đã làm):

• dữ liệu phân tích: khách hàng đã nói gì với bạn khi bạn nói về yêu cầu lần đầu tiên?

• lời đề nghị bạn đã thực hiện:

  • tài liệu yêu cầu sản phẩm
  • và tài liệu đặc tả chức năng

  mà cùng nhau hoạt động như một loại hợp đồng về những gì bạn phải làm và những gì bạn mong đợi
  khách hàng sẽ cung cấp trong quá trình phát triển cũng như thời gian và chi phí ước tính.

• các đặc điểm kỹ thuật bao gồm các giao thức xem xét, usecase và testplans, testresults

• thiết kế trong UML và tất cả các tài liệu tương ứng

• tài liệu về sourcecode (doxygen hoặc bất cứ điều gì)

• hướng dẫn sử dụng và cài đặt

• lượng tài nguyên thực tế cuối cùng (thời gian và tiền bạc) được sử dụng cho dự án, do đó bạn có thể viết hóa đơn

• một số khách hàng muốn các giao thức cuộc họp, sau đó là phần mở rộng của "tài liệu quyết định" được đề cập ở trên

Hy vọng đó là những gì bạn đang tìm kiếm.

Thực hiện theo bất kỳ tài liệu nào được áp dụng cho dự án của bạn từ sau. Bạn có thể đã có một số trong số họ.

Tài liệu kỹ thuật:

• Chi tiết về PHP và thông tin về cách nó hữu ích cho dự án
• Chi tiết về mặt sau và thông tin về cách nó hữu ích cho dự án
• Thông tin về kết nối cơ sở dữ liệu cùng với hình ảnh phù hợp mô tả luồng dữ liệu
• Thông tin về các ngôn ngữ lập trình hoặc ứng dụng khác có liên quan đến dự án như XML, HTML, v.v.
• Câu hỏi thường gặp

Chuẩn bị tài liệu với ảnh chụp màn hình và tô sáng mã liên quan (nếu cần) cho các mục sau:

• Thông tin trên ứng dụng giao diện người dùng như đối tượng hoặc điều khiển, thuộc tính đối tượng, v.v.
• Thông tin về truy vấn cơ sở dữ liệu (nếu chưa có)
• Thông tin về các thuộc tính cơ sở dữ liệu như Khóa chính, Khóa ngoài, v.v. và cách chúng đảm bảo tính nhất quán và chính xác của dữ liệu.
• Hướng dẫn chi tiết trong toàn dự án bằng cách sử dụng ảnh chụp màn hình của tất cả các loại màn hình có thể sử dụng cả mặt trước cũng như mặt sau sau khi chạy với dữ liệu mẫu, mà không lặp lại loại dữ liệu hoặc màn hình tương tự, theo thứ tự hợp lý.

• Nhập dữ liệu không hợp lệ và hiển thị là không thể làm như vậy vì bạn đã thực hiện xác thực dữ liệu ở mặt trước và mặt sau.
  /* This step is not applicable if you have not used any object for getting direct input from the user like Text Field as it is obvious that you cannot get invalid data through indirect input. */

• Cho thấy rằng không có lỗi trong chương trình hoặc sự không nhất quán trong dữ liệu nếu có sự cố bất ngờ trong máy chủ hoặc hệ thống máy khách bằng cách giải thích mã liên quan.

• Sau khi đưa dữ liệu mẫu qua giao diện người dùng, bạn có thể bao gồm các truy vấn mẫu ở phía sau để truy xuất trực tiếp dữ liệu từ máy chủ và cũng bao gồm các truy vấn DML mẫu có thể giúp chuẩn bị số liệu thống kê quan trọng của dữ liệu của bạn.

Bạn nên tự kiểm tra chúng trước khi ghi lại chúng để nếu khách hàng của bạn yêu cầu bản demo với dữ liệu mẫu, bạn có thể hiển thị cách dự án thực sự hoạt động. Ngoài ra, hãy đảm bảo rằng mã mặt trước của bạn có các dòng nhận xét phù hợp.

• Cuối cùng kết luận với các số liệu thống kê như tổng số dòng mã, tổng số ngày dành cho dự án, tổng số lần bạn đã kiểm tra dự án, danh sách tất cả các ứng dụng được sử dụng và thông tin kỹ thuật và phi kỹ thuật khác.

  
  Tài liệu phi kỹ thuật:

• Chi tiết cấp phép của dự án, nếu có.
• Các khía cạnh thương mại của dự án, nếu có.

Hãy cảnh giác

Các tài liệu tiềm năng mà bạn có thể cung cấp cho khách hàng là gần như vô tận. Thời gian bổ sung cần thiết để tạo tài liệu bạn chưa có là chưa được trả tiền.

Tại sao khách hàng muốn tài liệu này (hơn và trên mã nguồn)? Điều gì sẽ được thực hiện với nó? Nó dành cho ai?

Các câu trả lời cho những câu hỏi này sẽ giúp thu hẹp phạm vi của những gì sẽ cung cấp.

Điều quan trọng là bạn và khách hàng đồng ý chính xác tài liệu nào sẽ được cung cấp và liệu có bất kỳ nỗ lực bổ sung nào sẽ được bồi thường hay không.

Đừng chơi trò chơi đoán. Hầu hết các tài liệu kỹ thuật sẽ vô dụng đối với khách hàng điển hình (phi kỹ thuật).

Tôi có thể chia nó thành một vài loại tài liệu:

Hướng dẫn:

• Hướng dẫn cài đặt, cách thiết lập tính năng này trên máy chủ.
• Hướng dẫn của quản trị viên, về cách định cấu hình và chạy ứng dụng để có hiệu suất tối ưu. Bảo mật cũng sẽ là thứ cần được đề cập ở đây để người ta biết ứng dụng này có mật khẩu gì và sử dụng để chạy.

Ủng hộ:

• Nếu có vấn đề, bạn sẽ đề nghị loại thủ tục nào? Bạn đang cung cấp hỗ trợ trong một khoảng thời gian? Có lẽ tôi vẫn sẽ cung cấp một hoặc hai hướng dẫn trong lĩnh vực này để người khác biết một số điều dễ dàng hơn để thử như khởi động lại dịch vụ hoặc khởi động lại máy chủ.

Điểm tích hợp:

• Có điểm tích hợp bên thứ 3 nào cho ứng dụng này khiến ứng dụng dựa vào các nhà cung cấp khác ngoài mã của bạn không?