Dự án DIPY

Trang này chứa thông tin chi tiết về một dự án viết nội dung kỹ thuật đã được chấp nhận tham gia Google Season of Docs.

Tóm tắt dự án

Tổ chức nguồn mở:

DIPY

Người viết nội dung kỹ thuật:

Areesha Tariq

Tên dự án:

Cấu trúc lại cấp cao và tập trung vào người dùng cuối

Độ dài dự án:

Thời hạn 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 nội dung 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, hướng dẫn sử dụng, hướng dẫn sử dụng, nội dung mô tả dự án chất lượng cao. Tôi sống ở Hồi giáo, Pakistan (Múi giờ: UTC + 5). Hiện tại, tôi đang là thực tập sinh tại bộ phận Tiếp cận và sẽ tiếp tục làm việc cho đến ngày 18 tháng 8. Tôi đã tham gia Google Season of Docs với vai trò là Nhà văn kỹ thuật trong tổ chức OpenELIS Global. Tài liệu ban đầu bằng tiếng Pháp, bị hạn chế và đã lỗi thời, vì vậy, tôi đã tạo một tài liệu mới và đầy đủ hơn cho người dùng cuối bằng tiếng Anh. Tôi được chọn tham gia chương trình Outreachy trong tổ chức Perl & Raku cho vòng tháng 5 đến tháng 8 năm 2020 với vai trò là nhà phát triển phụ trợ của máy chủ Open Food Facts. Bên cạnh việc phát triển phần 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 cho các mô-đun và hàm ở định dạng POD. Năm ngoái, tôi bước vào thế giới mã nguồn mở khi đóng góp trong một số dự án nguồn mở và sau đó tham gia Mùa tài liệu của Google. Và năm nay, tôi được chọn trong chương trình Tiếp cận. Đây là nền tảng hỗ trợ tính đa dạng trong phần mềm nguồn mở và phần mềm miễn phí. Tôi nắm rất rõ Git vì dự án Outreachy 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 hơn 3 năm qua và đã sử dụng các lệnh dòng lệnh kể từ đó.

Các công cụ và ngôn ngữ tài liệu mà tôi đã sử dụng là Sphinx, Read the docs, Markdown. Tôi thích ý tưởng này và muốn thực hiện vì tôi có kinh nghiệm phù hợp, đồng thời cũng muốn vậ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. Điều này sẽ giúp tôi hiểu rõ hơn về hình ảnh thần kinh và giúp 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ế dành cho bác sĩ, bệnh nhân, phòng thí nghiệm, tài xế xe cứu thương. Tôi đã 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. Điều này sẽ giúp tôi tạo ra tài liệu dễ hiểu hơn cho khán giả.

Tôi đã xem qua tài liệu về DIPY và ghi lại một số lỗi trong tài liệu đó. Tài liệu này 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ể. Việc điều hướng có thể trở nên tẻ nhạt và tốn thời gian, đặc biệt là đối với người dùng mới. Người dùng có thể gặp khó khăn trong việc lấy thông tin từ hướng dẫn. Nội dung của tài liệu cần được cải thiện. Là một người dùng mới, tôi thấy khó truy cập vào hướng dẫn sử dụng và hướng dẫn dành cho nhà phát triển. Tài liệu cần được định hình lạ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 được Tài liệu thiếu tính nhất quán

Tôi dự định làm như sau:

Xác định cấu trúc và mẫu cụ thể cho tài liệu Tái định hình tài liệu để người dùng có thể dễ dàng điều hướng và tìm thấy 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 để thu hút cộng đồng tham gia vào công việc tài liệu khác Xác định mẫu cho hướng dẫn sử dụng và hướng dẫn dành cho nhà phát triển Xác định mẫu cho hướng dẫn đóng góp Viết lại, tái cấu trúc 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 hình ảnh không phải văn bản để nâng cao nội dung giải thích bằng văn bản Cải thiện tính nhất quán trên tài liệu Tạo tài liệu cho giao diện dòng lệnh mới

Hướng dẫn sử dụng:

Đối với hướng dẫn sử dụng, tôi sẽ tập trung 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. Tránh sử dụng thuật ngữ, từ viết tắt và thông tin nội bộ khác mà người dùng mới có thể không 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 hình ảnh, 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 hoạt động của hệ thống. Tài liệu tốt cần có hệ phân cấp tiêu đề và tiêu đề phụ để người dùng biết nội dung của từng phần. Và 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 nội dung hỗ trợ tiếp cận. Tất cả tài liệu và hướng dẫn đều phải tuân theo một kiểu nhất quán. Bạn phải sử dụng phông chữ và màu sắc bổ sung nhất quán trên nhiều tài liệu. 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 về cách để thành công với hệ thống.

Hướng dẫn cho nhà phát triển:

Hướng dẫn dành 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 đóng góp vào mã nguồn của DIPY. Công cụ này cố gắng trình bày nhiều lựa chọ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 được định hình và tái cấu trúc. Tôi sẽ viết lại nội dung của hướng dẫn dành cho nhà phát triển. Các phần phụ thuộc của bản dựng, hướng dẫn đóng góp, hướng dẫn về phong cách, quy ước lập trình, hướng dẫn tài liệu, cách 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 người đóng góp mới háo hức mong muốn nhanh chóng đóng góp vào dự án của bạn để đóng góp nguồn mở đầu tiên, họ sẽ dựa vào hướng dẫn đóng góp để trở thành hướng dẫn. Do đó, các nguyên tắc sẽ dễ đọc, kỹ lưỡng và thân thiện. Hướng dẫn đóng góp là những tài liệu hữu ích giúp mọi người biết cách đóng góp cho dự án nguồn mở. Người dùng phải có thể đóng góp cho dự án một cách dễ dàng và minh bạch nhất có thể, cho dù đó là: gửi bản sửa lỗi, báo cáo lỗi, trở thành người duy trì, thảo luận về trạng thái hiện tại của mã hay đề xuất tính năng mới.

TEMPLATE

Đây là một trong những mẫu có thể dùng cho hướng dẫn đóng góp. Bạn có thể sửa đổi, thêm hoặc xoá các phần theo yêu cầu của tài liệu.

Đóng góp cho DIPY

• Ghi chú chào mừng

TOC

Bộ 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 đơn vị bảo trì dự án
• Phạm vi

Phạm vi của Quy tắc ứng xử

Tôi cần biết những gì để trợ giúp?

Nếu bạn muốn đóng góp mã, dự án của chúng tôi 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ã thì cũng không sao! Bạn cũng có thể xem các vấn đề về tài liệu [đường liên kết đến nhãn hoặc thẻ tài liệu trên công cụ theo dõi lỗi] hoặc các vấn đề về thiết kế mà chúng tôi gặp phải [đường liên kết đến nhãn hoặc thẻ thiết kế trên công cụ theo dõi lỗi nếu dự án của bạn theo dõi các 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. Thêm danh sách các tài nguyên (hướng dẫn, video, sách) được liệt kê bằng dấu đầu dòng mà những người đóng góp 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 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 của nhóm
• Tốc độ phản hồi

Cách yêu cầu cải tiến

• Trước khi gửi Đề xuất cải tiến
• Làm cách nào để gửi đề xuất cải tiến (có giá trị)?

Đóng góp mã đầu tiên

• Vấn đề mới bắt đầu
• Các vấn đề mong muốn được 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 không kiểm tra được trạng thái thì sao?

• Viết mã kiểm thử
• Phạm vi kiểm thử

Hướng dẫn phong cách

• Thông báo xác nhận của 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: [e-mail], cuộc trò chuyện IRC hoặc [liệt kê mọi nền tảng giao tiếp khác mà dự án của bạn sử dụng].

Giấy phép

Phần này sẽ cho bạn biết về giấy phép của dự án.

Cam kết về thời gian và cách giao tiếp:

Tôi sẽ dành hơn 45 giờ mỗi tuần cho công việc này. Tuy nhiên, trong trường hợp có sự cố, tôi sẽ bù lại những giờ đó vào cuối tuần. Trong thời gian gắn bó với cộng đồng, tôi sẽ thảo luận về phương thức liên lạc và sẽ chốt các cuộc họp hằng tuần, phương thức và thời gian cho các cuộc họp đó với người cố vấn của mình. Tôi sẽ cập nhật cho người cố vấn về công việc của mình; sẽ chia sẻ thông tin chi tiết về công việc của mình qua email với người cố vấn. Tôi thích dùng TeamViewer hơn 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.