Xin chào, Habr! Tên tôi là Lesha, tôi là nhà phân tích hệ thống cho một trong các nhóm sản phẩm của Alfa-Bank. Bây giờ tôi đang phát triển một ngân hàng trực tuyến mới dành cho các pháp nhân và doanh nhân cá nhân.
Và khi bạn là một nhà phân tích, đặc biệt là trong một kênh như vậy, bạn không thể đi đến đâu nếu không có tài liệu và làm việc chặt chẽ với nó. Và tài liệu là thứ luôn đặt ra rất nhiều câu hỏi. Tại sao ứng dụng web không được mô tả? Tại sao thông số kỹ thuật chỉ ra cách thức hoạt động của dịch vụ, nhưng nó lại không hoạt động như vậy? Tại sao chỉ có hai người, một trong số họ đã viết nó, có thể hiểu được thông số kỹ thuật?
Tuy nhiên, không thể bỏ qua tài liệu vì những lý do rõ ràng. Và để làm cho cuộc sống của chúng tôi dễ dàng hơn, chúng tôi quyết định đánh giá chất lượng tài liệu. Chúng tôi đã làm điều này chính xác như thế nào và chúng tôi đưa ra những kết luận gì vẫn chưa được xác định.
Chất lượng tài liệu
Để không lặp lại “Ngân hàng Internet mới” vài chục lần trong văn bản, tôi sẽ viết NIB. Hiện tại, chúng tôi có hơn chục nhóm làm việc để phát triển NIB cho các doanh nhân và pháp nhân. Hơn nữa, mỗi người trong số họ đều tạo tài liệu riêng cho dịch vụ hoặc ứng dụng web mới từ đầu hoặc thực hiện các thay đổi đối với tài liệu hiện tại. Với cách tiếp cận này, về nguyên tắc liệu tài liệu có thể có chất lượng cao không?
Và để xác định chất lượng của tài liệu, chúng tôi đã xác định ba đặc điểm chính.
- Nó phải được hoàn thành. Điều này nghe có vẻ giống thuyền trưởng, nhưng điều quan trọng cần lưu ý. Nó nên mô tả chi tiết tất cả các yếu tố của giải pháp được triển khai.
- Nó phải có liên quan. Nghĩa là, tương ứng với việc triển khai giải pháp hiện tại.
- Nó có thể hiểu được. Để người sử dụng nó hiểu chính xác giải pháp được thực hiện như thế nào.
Tóm tắt - tài liệu đầy đủ, cập nhật và dễ hiểu.
Опрос
Để đánh giá chất lượng của tài liệu, chúng tôi quyết định phỏng vấn những người trực tiếp làm việc với nó: các nhà phân tích của NIB. Người trả lời được yêu cầu đánh giá 10 nhận định theo sơ đồ “Trên thang điểm từ 1 đến 5 (hoàn toàn không đồng ý - hoàn toàn đồng ý)”.
Các tuyên bố phản ánh đặc điểm của tài liệu định tính và ý kiến của những người biên soạn khảo sát về tài liệu NIB.
- Tài liệu dành cho các ứng dụng NIB được cập nhật và hoàn toàn nhất quán với việc triển khai chúng.
- Việc triển khai các ứng dụng NIB được ghi lại đầy đủ.
- Tài liệu dành cho các ứng dụng NIB chỉ cần thiết để hỗ trợ chức năng.
- Tài liệu dành cho các ứng dụng NIB hiện có tại thời điểm chúng được gửi để được hỗ trợ chức năng.
- Các nhà phát triển ứng dụng NIB sử dụng tài liệu để hiểu những gì họ cần triển khai.
- Có đủ tài liệu để các ứng dụng NIB hiểu cách chúng được triển khai.
- Tôi cập nhật kịp thời tài liệu về các dự án NIB nếu chúng được hoàn thiện (bởi nhóm của tôi).
- Các nhà phát triển ứng dụng NIB xem xét tài liệu.
- Tôi hiểu rõ về cách chuẩn bị tài liệu cho các dự án NIB.
- Tôi hiểu khi nào cần viết/cập nhật tài liệu cho các dự án NIB.
Rõ ràng là chỉ trả lời “Từ 1 đến 5” có thể không tiết lộ các chi tiết cần thiết, vì vậy một người có thể để lại nhận xét về từng mục.
Chúng tôi đã thực hiện tất cả những điều này thông qua Slack của công ty - chúng tôi chỉ gửi lời mời đến các nhà phân tích hệ thống để thực hiện một cuộc khảo sát. Có 15 nhà phân tích (9 người từ Moscow và 6 người từ St. Petersburg). Sau khi cuộc khảo sát hoàn tất, chúng tôi đã tính điểm trung bình cho mỗi câu trong số 10 câu phát biểu, sau đó chúng tôi sẽ chuẩn hóa điểm này.
Đây là những gì đã xảy ra.
Cuộc khảo sát cho thấy mặc dù các nhà phân tích có xu hướng tin rằng việc triển khai các ứng dụng NIB được ghi chép đầy đủ nhưng họ không đưa ra thỏa thuận rõ ràng (0.2). Lấy một ví dụ cụ thể, họ chỉ ra rằng một số cơ sở dữ liệu và hàng đợi từ các giải pháp hiện có không được tài liệu đề cập. Nhà phát triển có thể nói với nhà phân tích rằng không phải mọi thứ đều được ghi lại. Nhưng luận điểm mà các nhà phát triển xem xét tài liệu cũng không nhận được sự hỗ trợ rõ ràng (0.33). Nghĩa là vẫn còn nguy cơ mô tả không đầy đủ các giải pháp đã triển khai.
Mức độ liên quan dễ dàng hơn - mặc dù một lần nữa không có sự thống nhất rõ ràng (0,13), các nhà phân tích vẫn có xu hướng xem xét tài liệu có liên quan. Các nhận xét cho phép chúng tôi hiểu rằng các vấn đề liên quan thường ở phía trước hơn là ở giữa. Tuy nhiên, họ không viết bất cứ điều gì cho chúng tôi về việc hỗ trợ.
Về việc liệu bản thân các nhà phân tích có hiểu khi nào cần viết và cập nhật tài liệu hay không, thỏa thuận này thống nhất hơn nhiều (1,33), bao gồm cả thiết kế của nó (1.07). Điều bất tiện được lưu ý ở đây là thiếu các quy tắc thống nhất để lưu giữ tài liệu. Vì vậy, để không bật chế độ “Ai vào rừng, ai lấy củi” thì phải làm việc dựa trên các ví dụ về tài liệu hiện có. Do đó, mong muốn hữu ích là tạo ra một tiêu chuẩn để quản lý tài liệu và phát triển các mẫu cho các bộ phận của chúng.
Tài liệu dành cho các ứng dụng NIB hiện có tại thời điểm nộp đơn xin hỗ trợ chức năng (0.73). Điều này có thể hiểu được vì một trong những tiêu chí để gửi dự án để được hỗ trợ chức năng là tài liệu được cập nhật. Chỉ cần hiểu cách thực hiện (0.67) là đủ, mặc dù đôi khi vẫn còn thắc mắc.
Nhưng điều mà những người được hỏi không đồng ý (khá nhất trí) là về nguyên tắc, tài liệu dành cho các ứng dụng NIB chỉ cần thiết để hỗ trợ chức năng (-1.53). Các nhà phân tích được nhắc đến thường xuyên nhất với tư cách là người sử dụng tài liệu. Phần còn lại của nhóm (nhà phát triển) - ít thường xuyên hơn. Hơn nữa, các nhà phân tích tin rằng các nhà phát triển không sử dụng tài liệu để hiểu những gì họ cần triển khai, mặc dù không nhất trí (-0.06). Nhân tiện, điều này cũng được mong đợi trong điều kiện việc phát triển mã và viết tài liệu được tiến hành song song.
Điểm mấu chốt là gì và tại sao chúng ta cần những con số này?
Để cải thiện chất lượng của tài liệu, chúng tôi quyết định thực hiện những việc sau:
- Yêu cầu nhà phát triển xem lại các tài liệu bằng văn bản.
- Nếu có thể, hãy cập nhật tài liệu kịp thời, trước tiên.
- Tạo và áp dụng tiêu chuẩn ghi lại các dự án NIB để mọi người có thể nhanh chóng hiểu được các thành phần hệ thống nào và cách mô tả chính xác. Vâng, phát triển các mẫu phù hợp.
Tất cả điều này sẽ giúp nâng cao chất lượng tài liệu lên một tầm cao mới.
Ít nhất tôi hy vọng như vậy.
Nguồn: www.habr.com