Chọn chỉ số phù hợp cho dự án của bạn

Hướng dẫn này nhằm giúp các tổ chức nắm được những loại vấn đề nào có thể được giải quyết nhờ tài liệu hữu ích hơn và cách chọn chỉ số phù hợp cho dự án tài liệu.

Giai đoạn hiện tại:
Chương trình Phần Tài liệu năm 2021 đã kết thúc vào ngày 14 tháng 12 năm 2021. Hãy xem dòng thời gian.

Nêu rõ vấn đề của bạn

Trước khi bắt đầu chọn một chỉ số, hãy đảm bảo bạn hiểu rõ về vấn đề mà mình đang cố gắng giải quyết. Hãy trả lời thật cụ thể.

  • “Việc yêu cầu kéo tài liệu hướng dẫn làm quen với ứng dụng mất quá nhiều thời gian để hợp nhất. Những người đóng góp từ bỏ và biến mất."
  • “Chúng tôi nhận thấy có quá nhiều vấn đề đã được mở ra để tìm hiểu mã lỗi.”
  • “Quy trình CI/CD của chúng tôi không ổn định. Có quá nhiều lượt kiểm thử không thành công vì các lý do không dễ hiểu.”
  • "Cuộc họp hằng tuần của chúng tôi trông có vẻ khó chịu."

Xây dựng giả thuyết

Hãy tìm nguyên nhân và kết quả. Đâu có thể là nguyên nhân gây ra vấn đề mà bạn đã nêu? Xin lưu ý rằng vấn đề có thể do nhiều nguyên nhân hoặc nguyên nhân chồng chéo lên nhau.

  • "Việc hợp nhất các yêu cầu lấy dữ liệu cho tài liệu hướng dẫn làm quen sẽ mất rất nhiều thời gian vì chúng tôi không có hướng dẫn rõ ràng về quy tắc lập trình. Người đánh giá hoặc là trì hoãn việc đánh giá PR vì họ không biết phải làm gì, hoặc họ liên tục trao đổi với cộng tác viên về cách định dạng."
  • “Người dùng phải mở vấn đề vì họ không tìm thấy thông tin về mã lỗi trong tài liệu.”
  • “Các thử nghiệm CI/CD của chúng tôi không thành công do chúng tôi gặp phải tình trạng giới hạn và hết thời gian chờ của nhà cung cấp.”
  • “Mọi người thường gắt gỏng trong các cuộc họp hằng tuần của chúng tôi vì các cuộc họp diễn ra vào 5:30 sáng theo múi giờ của họ.”

Đề xuất giải pháp

Đây có phải là vấn đề có thể giải quyết bằng tài liệu mới hay phù hợp hơn không?

  • "Nếu chúng tôi có hướng dẫn về quy tắc lập trình, người cam kết có thể kiểm tra trước khi gửi PR của họ. Người đánh giá sẽ biết cần kiểm tra nội dung gì. Người đánh giá và cộng tác viên không cần phải tranh luận về định dạng, giọng điệu và phong cách nữa."
  • “Nếu chúng tôi có tài liệu về mã lỗi, người dùng có thể tìm thấy câu trả lời ở đó, thay vì mở vấn đề”.
  • "Hừm, có vẻ như tài liệu tốt hơn sẽ giải quyết được vấn đề CI/CD của chúng ta."
  • “Chúng ta có thể bắt đầu mỗi cuộc họp bằng một câu đùa cơ bản! Tạo một tuyển tập gồm những câu đùa vui nhộn sẽ giúp chúng tôi bắt đầu cuộc họp với một nụ cười."

Cụ thể

Bạn có thể định lượng vấn đề này không?

  • “Việc hợp nhất các PR mất quá nhiều thời gian” có nghĩa là gì? 2 tháng? 2 tuần? Người đóng góp sẽ đợi bao lâu để được xem xét trước khi từ bỏ?”
  • "Có bao nhiêu vấn đề liên quan đến mã lỗi là "quá nhiều vấn đề"?"
  • "Hmmm ... gắt gỏng "quá gắt gỏng"?"

Kiểm tra khả năng đo lường

Bạn sẽ kiểm tra chỉ số mà bạn đề xuất như thế nào? Có thể đo lường dễ dàng và chính xác không? Việc đo lường có phụ thuộc vào người tiến hành đo lường không?

  • “Chúng tôi có thể dễ dàng đo lường thời gian mà một yêu cầu lấy dữ liệu đã được mở và khoảng thời gian kể từ khi yêu cầu xem xét được yêu cầu. Chúng tôi thực sự không thể đo lường chính xác khi một người đóng góp từ bỏ."
  • “Chúng tôi có thể đếm số lượng vấn đề được gắn thẻ "mã lỗi" hoặc lượt tìm kiếm trong các vấn đề đối với văn bản mã lỗi."
  • Chúng tôi thực sự không thể đo lường sự thô thiển của mọi người theo cách khéo léo hoặc chính xác."

Thêm chỉ số phụ

Có chỉ số nào khác giúp bạn nắm được liệu tài liệu có giúp bạn giải quyết vấn đề hay không? Trong mọi trường hợp, chỉ số mục tiêu của bạn có giống nhau không?

  • “Các PR dài hơn sẽ mất nhiều thời gian xem xét hơn; chúng ta nên có các ngưỡng khác nhau cho các kích thước PR khác nhau. Chúng tôi muốn đo lường thời gian hợp nhất cho các PR nhỏ, trung bình, lớn và lớn."
  • “Chúng tôi có thể kiểm tra số lượt truy cập mà tài liệu về mã lỗi của chúng tôi nhận được và xem liệu con số đó có liên quan đến số vấn đề đã mở ít hơn hay không.

Chọn khoảng thời gian

  • “Chúng tôi cho rằng cần 2 tuần để hợp nhất các PR có quy mô từ nhỏ đến trung bình; và tất cả các PR nên được hợp nhất trong vòng một tháng. Vì vậy, chúng tôi sẽ đo lường hai tuần một lần.”
  • “Việc cập nhật số lượng vấn đề liên quan đến mã lỗi hằng ngày là không hợp lý vì thời gian thông thường để xử lý một vấn đề là một tuần. Chúng tôi sẽ đo lường chỉ số này hằng tuần."

Đặt mục tiêu

Bạn cần thấy mức độ thay đổi như thế nào trong chỉ số đã chọn để xác định rằng dự án đã thành công? Hãy cân nhắc đặt các mục tiêu định lượng cho các chỉ số mà bạn chọn.

  • "Nếu chúng tôi đạt được mục tiêu chấm dứt mọi PR mới trong vòng chưa đầy một tháng, thì đó sẽ là thành công. Nếu thời gian trung bình để chốt các PR lớn của chúng tôi giảm đi hai tuần, thì đó sẽ là một thành công lớn."
  • “Tốt nhất là chúng tôi sẽ không thấy có vấn đề mới liên quan đến lỗi. Tuy nhiên, chúng tôi sẽ coi dự án của mình thành công nếu thấy số vấn đề liên quan đến lỗi giảm 50%."