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ở:
- OpenMRS.org
- Người viết nội dung kỹ thuật:
- batbrain7
- Tên dự án:
- Tài liệu về API OpenMRS REST
- Thời lượng dự án:
- Thời gian tiêu chuẩn (3 tháng)
Mô tả dự án
Tôi sẽ chia nhỏ đề xuất của mình thành các phần khác nhau và sẽ thực hiện theo quy trình như tài liệu về API Google Maps và tài liệu về API GitHub.
Ngoài những điều này, tôi cũng muốn đề xuất cấu trúc readme cho tài liệu API do realworld.io thực hiện: https://github.com/gothinkster/realworld/tree/master/api
Cá nhân tôi thấy tài liệu này rất dễ hiểu và dễ sử dụng.
Đề xuất của tôi sẽ chủ yếu bao gồm 3 phần :
Phần giới thiệu ngắn gọn về API, về OpenMRS, cách sử dụng API cũng như nội dung tiếp theo.
Cách lấy khoá API và quy trình xác thực cần thiết nói chung để tạo yêu cầu API. Phần này sẽ bao gồm một ví dụ mẫu về các loại xác thực có trong API, cũng như các khoá và giá trị cần có trong API, cũng như các loại giá trị được chấp nhận tương ứng với khoá trong phần đó. Mã mẫu bằng bất kỳ ngôn ngữ nào cũng sẽ hỗ trợ và giải thích rõ cách viết tiêu đề, định dạng phản hồi cũng như các tham số truy vấn khác trong API.
Các loại phản hồi mà API tìm nạp, loại JSON hoặc bất kỳ loại kết quả nào khác do API trả về sẽ được đề cập.
Các tuyến API khác nhau và tất cả tham số cần được gửi cùng với các tuyến đó, tiêu đề và nội dung khác. Mỗi API sẽ được hỗ trợ bằng mã mẫu bằng một vài ngôn ngữ mô tả cách yêu cầu được thực hiện trong khi viết mã cho nó, ngoài các mã lỗi chung có thể gặp phải với mỗi API cũng nên được đề cập.
Đây là ý tưởng chung về cách tài liệu sẽ được xác định cho API REST.
Lịch trình của dự án như sau :
1/8 – 1/9
Làm quen với người cố vấn và thảo luận chi tiết hơn về cấp độ tài liệu cần thiết ở các phần khác nhau của cơ sở mã, đồng thời thảo luận về việc phân tích sâu hơn trong tài liệu cấp thấp và cấp cao. Tôi cũng sẽ dành thời gian này để tìm hiểu cơ sở mã và nghiên cứu các khái niệm để có thể ghi chép chúng tốt hơn.
Tuần 1 và 2
Tôi sẽ cập nhật và mở rộng hướng dẫn dành cho cộng tác viên. Tôi sẽ cải thiện tài liệu về cách tạo mã nguồn. Tôi cũng sẽ thêm một phần tài liệu về cách cộng tác viên mới có thể đóng góp tài liệu. Tôi sẽ nghiên cứu tài liệu về API khác nhau và bắt đầu từ phần giới thiệu và thêm phương thức xác thực cho API.
Tuần 3 – 8
Tôi sẽ thêm các tuyến và phản hồi API cùng với một số mã mẫu cho từng loại API (có thể có những loại API tương tự).
Tuần 9 và tuần 10
Thêm cấu trúc tài liệu API bằng cách sử dụng các đường liên kết, chẳng hạn như một chỉ mục được liên kết cho tài liệu API dài và chia nhỏ hơn nữa trên cơ sở khác, chẳng hạn như các phần mã, tổng quan, tham số, điểm cuối gốc.
Tuần cuối cùng
Tôi sẽ dùng tuần cuối cùng để chuẩn bị báo cáo cuối cùng về công việc đã thực hiện trong 12 tuần làm tài liệu. Tôi cũng sẽ dành thời gian để xem xét và hoàn thiện tài liệu.