Trang này chứa thông tin chi tiết về một dự án viết kỹ thuật được chấp nhận cho Phần Google Tài liệu.
Tóm tắt dự án
- Tổ chức nguồn mở:
- PHÁT NGHĨA
- Người viết nội dung kỹ thuật:
- Areesha Tariq
- Tên dự án:
- Tái cấu trúc cấp cao và tập trung vào người dùng cuối
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Tôi là Kỹ sư phần mềm và có chuyên môn về viết kỹ thuật. Tôi có hơn 4 năm kinh nghiệm trong việc biên soạn tài liệu phần mềm chất lượng cao, hướng dẫn sử dụng, hướng dẫn sử dụng và nội dung mô tả dự án. Tôi sống ở Islamabad, Pakistan (Múi giờ: UTC + 5). Hiện tại, tôi đang làm thực tập sinh tại PfPy đến hết ngày 18 tháng 8. Tôi đã tham gia Phần Tài liệu của Google với tư cách là Người viết kỹ thuật trong tổ chức OpenELIS Global. Tài liệu gốc bằng tiếng Pháp, có giới hạn và đã lỗi thời, vì vậy, tôi đã tạo một tài liệu đầy đủ và cập nhật dành cho người dùng cuối bằng tiếng Anh. Tôi được chọn làm nhà phát triển phụ trợ của máy chủ Open Food Facts của tổ chức Perl & Raku vào khoảng tháng 5 đến tháng 8 năm 2020. Bên cạnh phát triển hệ thống phụ trợ, một trong những nhiệm vụ chính của chương trình thực tập này là tạo tài liệu về các mô-đun và chức năng theo định dạng POD. Năm ngoái, tôi bước vào thế giới nguồn mở khi đóng góp trong một số dự án nguồn mở và sau đó tham gia chương trình Phần Tài liệu của Google. Và năm nay, tôi đã được chọn tham gia Conversationy hỗ trợ tính đa dạng trong phần mềm nguồn mở và miễn phí. Tôi hiểu rõ Git vì dự án Reachy của tôi được lưu trữ trên GitHub và tôi đã thường xuyên đóng góp cho Open Food Facts và Mozilla Fenix kể từ tháng 3. Tôi là người dùng Linux được hơn 3 năm và đã sử dụng các lệnh trong thiết bị đầu cuối kể từ đó.
Các công cụ tài liệu và ngôn ngữ mà tôi đã sử dụng là Sphinx, Đọc tài liệu, Markdown. Tôi thích ý tưởng này và muốn thực hiện vì tôi có kinh nghiệm liên quan và tôi muốn dùng kiến thức và kỹ năng của mình để đóng góp cho DIPY. Tôi có kinh nghiệm trong lĩnh vực xử lý hình ảnh kỹ thuật số, thị giác máy tính, học máy. Việc này sẽ giúp tôi hiểu rõ hơn về hình ảnh thần kinh và giúp tôi tạo tài liệu. Tôi có nhiều kinh nghiệm trong lĩnh vực y tế. Tôi đã phát triển một trang web y tế cho bác sĩ, bệnh nhân, phòng thí nghiệm, tài xế xe cứu thương. Tôi từng làm việc trên một hệ thống khác được các bác sĩ, bệnh nhân, y tá, trợ lý phòng thí nghiệm và nhà nghiên cứu sử dụng. Việc này sẽ giúp tôi tạo tài liệu dễ hiểu hơn cho khán giả.
Tôi đã xem tài liệu về DIPY và đã chỉ ra một số thiếu sót trong tài liệu. Tài liệu của tôi có nhiều lỗ hổng mà tôi dự định cải thiện. Trạng thái hiện tại của tài liệu: Tài liệu thiếu cấu trúc và thiết kế cụ thể Có thể mất thời gian và tẻ nhạt, đặc biệt là đối với người dùng mới thao tác Người dùng có thể gặp khó khăn trong việc thu thập thông tin từ hướng dẫn Nội dung tài liệu cần cải thiện Là người dùng mới, tôi thấy khó khăn trong việc truy cập hướng dẫn sử dụng và hướng dẫn cho nhà phát triển. Tài liệu cần được thay đổi theo cách mà thông tin mà người dùng yêu cầu phải dễ dàng truy cập Tài liệu thiếu tính nhất quán
Tôi dự định làm những việc sau:
Xác định cấu trúc và mẫu cụ thể cho tài liệu Định hình lại tài liệu để người dùng dễ dàng di chuyển và tìm thông tin cần thiết Tạo lộ trình hoặc danh sách các mục công việc để tương tác với cộng đồng trong tài liệu tiếp theo Xác định các mẫu cho hướng dẫn sử dụng và hướng dẫn cho nhà phát triển Xác định các mẫu cho hướng dẫn đóng góp Viết lại, sắp xếp lại và cập nhật hướng dẫn sử dụng, hướng dẫn phát triển và hướng dẫn đóng góp (có thể giúp và thúc đẩy người dùng mới đóng góp cho dự án) Thêm tài liệu không phải văn bản để tăng tính nhất quán cho tài liệu
Hướng dẫn sử dụng:
Đối với hướng dẫn sử dụng, tôi sẽ tập trung vào việc sử dụng ngôn ngữ đơn giản, rõ ràng để giúp người dùng hiểu được ngay cả những hệ thống phức tạp nhất. Cần tránh sử dụng từ ngữ, từ viết tắt và thông tin nội bộ khác mà có thể người dùng mới chưa biết để mang lại trải nghiệm tốt hơn cho người dùng. Tôi cũng sẽ tập trung vào việc sử dụng nội dung trực quan (bao gồm hình ảnh, ảnh chụp màn hình có chú thích, đồ hoạ và video) để nhanh chóng cho người dùng biết cách thức hoạt động của hệ thống. Một tài liệu hiệu quả cần có một hệ thống phân cấp các tiêu đề và tiêu đề phụ cho phép người dùng biết được mỗi phần sẽ trình bày nội dung gì. Hệ thống phân cấp đó phải tuân theo một luồng logic giúp người dùng tìm hiểu cách sử dụng hệ thống theo cách hữu ích nhất. Một trong những mục tiêu chính của dự án này là tạo ra nội dung dễ tiếp cận. Tất cả các tài liệu và hướng dẫn phải tuân theo một phong cách nhất quán. Việc sử dụng phông chữ nhất quán và màu sắc tương phản cho nhiều tài liệu là bắt buộc. Tôi sẽ đảm bảo rằng người dùng có quyền truy cập vào nhiều tài nguyên của tổ chức hơn để gặt hái thành công với hệ thống.
Hướng dẫn cho nhà phát triển:
Hướng dẫn cho nhà phát triển bao gồm hướng dẫn và tài liệu tham khảo chuyên sâu để hỗ trợ nhà phát triển tạo nội dung đóng góp cho mã nguồn DIPY. Chiến lược này cố gắng vạch ra nhiều lựa chọn có sẵn cho bạn để bạn có thể sử dụng phương pháp phù hợp, tuỳ thuộc vào mục tiêu bạn muốn đạt được. Hướng dẫn phát triển cần định hình lại và tái cấu trúc. Tôi sẽ viết lại nội dung hướng dẫn cho nhà phát triển. Xây dựng các phần phụ thuộc, hướng dẫn đóng góp, hướng dẫn quy tắc, quy ước lập trình, hướng dẫn tài liệu, cài đặt môi trường phát triển, gỡ lỗi, hướng dẫn kiểm thử và các nội dung liên quan sẽ được đưa vào và giúp nhà phát triển dễ dàng truy cập. Khi những cộng tác viên mới háo hức thực hiện dự án của bạn để có đóng góp nguồn mở đầu tiên, họ coi các nguyên tắc đóng góp sẽ là kim chỉ nam dẫn dắt mình. Do đó, các nguyên tắc phải dễ đọc, đầy đủ và thân thiện. Hướng dẫn đóng góp là tài liệu hữu ích truyền đạt cách mọi người có thể đóng góp cho dự án nguồn mở. Việc đóng góp cho dự án nên được thực hiện dễ dàng và minh bạch nhất có thể cho người dùng, cho dù: Gửi bản sửa lỗi Báo cáo lỗi Trở thành người bảo trì Thảo luận về trạng thái hiện tại của mã Đề xuất tính năng mới
TEMPLATE
Đây là một trong các mẫu bạn có thể dùng cho hướng dẫn đóng góp. Tài liệu có thể được sửa đổi và có thể thêm hoặc xoá các phần tuỳ theo yêu cầu của tài liệu.
Đóng góp cho DIPY
- Ghi chú chào mừng
Bảng điều khiển âm thanh bên ngoài
Quy tắc ứng xử
- Tiêu chuẩn của chúng tôi
- Ví dụ về hành vi góp phần tạo ra môi trường tích cực
- Ví dụ về hành vi không được chấp nhận của người tham gia
- Trách nhiệm của chúng tôi
- Trách nhiệm của bên bảo trì dự án
- Phạm vi
Phạm vi của Quy tắc ứng xử
Tôi cần biết điều gì để có thể trợ giúp bạn?
Nếu bạn đang muốn hỗ trợ việc đóng góp mã, dự án của chúng tôi sẽ sử dụng [chèn danh sách ngôn ngữ lập trình, khung hoặc công cụ mà dự án của bạn sử dụng]. Nếu bạn chưa sẵn sàng đóng góp mã, cũng không sao cả! Bạn cũng có thể xem các vấn đề về tài liệu [đường liên kết đến nhãn tài liệu hoặc thẻ trên công cụ theo dõi lỗi] hoặc vấn đề về thiết kế mà chúng tôi gặp phải [đường liên kết đến nhãn thiết kế hoặc thẻ trên công cụ theo dõi lỗi nếu dự án của bạn theo dõi vấn đề về thiết kế]. Nếu bạn quan tâm đến việc đóng góp mã và muốn tìm hiểu thêm về các công nghệ mà chúng tôi sử dụng, hãy xem danh sách bên dưới. Đưa ra danh sách tài nguyên có dấu đầu dòng (bản hướng dẫn, video, sách) mà cộng tác viên mới có thể sử dụng để tìm hiểu những điều người dùng cần biết để đóng góp cho dự án.
Thiết lập môi trường phát triển
Trong phần này, tôi sẽ thêm vào quy trình cài đặt và các phần phụ thuộc cần cài đặt. Cài đặt $project bằng cách chạy: cài đặt dự án
- Mã nguồn: github.com/$project/$project
- Công cụ theo dõi lỗi: github.com/$project/$project/issues
Cách đóng góp
Cách báo cáo lỗi
- Trước khi gửi báo cáo lỗi
- Làm cách nào để gửi báo cáo lỗi (tốt)?
Cách gửi nội dung thay đổi
- Giao thức yêu cầu kéo
- Phản hồi từ nhóm
- Tốc độ phản hồi
Cách yêu cầu nâng cao
- Trước khi gửi một đề xuất về tính năng nâng cao
- Làm cách nào để gửi đề xuất nâng cao (tốt)?
Lần đóng góp mã đầu tiên của bạn
- Các vấn đề cơ bản
- Vấn đề cần trợ giúp #### Yêu cầu lấy dữ liệu
- Quy trình tạo yêu cầu lấy dữ liệu
- Xác minh rằng tất cả các bước kiểm tra trạng thái đều đạt.
Nếu quy trình kiểm tra trạng thái không thành công thì sao?
- Kiểm tra viết
- Phạm vi kiểm thử
Hướng dẫn phong cách
- Thông báo cam kết Git
- Kiểu tiêu chuẩn
Hỗ trợ
Nếu bạn gặp vấn đề, vui lòng cho chúng tôi biết. Nếu cần trợ giúp, bạn có thể đặt câu hỏi trên danh sách gửi thư của chúng tôi tại địa chỉ project@google-groups.com, IRC Chat, hoặc [liệt kê bất kỳ nền tảng liên lạc nào khác mà dự án của bạn sử dụng].
Giấy phép
Phần này sẽ cho biết về giấy phép của dự án.
Cam kết thời gian và trao đổi thông tin:
Tôi sẽ làm việc thêm 45 giờ mỗi tuần, nhưng trong trường hợp có bất kỳ rủi ro nào, tôi sẽ đền bù cho số giờ đó vào cuối tuần. Trong giai đoạn gắn kết cộng đồng, tôi sẽ thảo luận về phương tiện liên lạc và sẽ hoàn thiện các cuộc họp hằng tuần, phương tiện và thời gian diễn ra các cuộc họp đó với người cố vấn của mình. Tôi sẽ thông báo cho người cố vấn cập nhật về công việc của tôi và sẽ chia sẻ thông tin chi tiết về công việc với cố vấn qua email. Tôi muốn dùng TeamViewer để trao đổi thông tin, vì ứng dụng này dễ sử dụng với nhiều tính năng như chia sẻ màn hình, v.v.