Halaman ini berisi detail project penulisan teknis yang diterima untuk Google Season of Docs.
Ringkasan project
- Organisasi open source:
- OpenMRS.org
- Penulis teknis:
- batbrain7
- Nama proyek:
- Dokumentasi OpenMRS REST API
- Durasi project:
- Durasi standar (3 bulan)
Project description
Saya akan memecah proposal saya menjadi beberapa bagian dan akan mengikuti alurnya seperti dokumentasi Google Maps API dan dokumentasi GitHub API.
Selain itu, saya juga ingin mengusulkan struktur readme untuk dokumentasi API yang dilakukan oleh realworld.io: https://github.com/gothinkster/realworld/tree/master/api
Secara pribadi, saya merasa dokumentasi ini sangat mudah dipahami dan digunakan.
Proposal saya terutama akan terdiri dari 3 bagian :
Bagian yang akan memberikan pengantar singkat tentang API, OpenMRS, dan cara API digunakan serta semua hal yang mengikutinya.
Cara mendapatkan kunci API dan autentikasi yang diperlukan secara umum untuk membuat permintaan API. Bagian ini akan berisi contoh jenis autentikasi yang ada di API serta kunci dan nilai yang harus ada untuknya, serta jenis nilai yang diterima sesuai dengan kunci di bagian tersebut. Contoh kode dalam bahasa apa pun akan membantu dan menjelaskan cara menulis header dan format respons serta parameter kueri lainnya di API.
Jenis respons yang diambil oleh API, jenis JSON, atau jenis hasil lainnya yang ditampilkan oleh API akan disebutkan.
Berbagai rute API dan semua parameter yang perlu dikirim bersama dengan rute tersebut, header, dan hal-hal lainnya. Setiap API akan dibantu dengan contoh kode dalam beberapa bahasa yang menjelaskan cara permintaan dibuat saat menulis kode untuknya, selain itu kode error umum yang dapat ditemukan dengan setiap API juga harus disebutkan.
Ini adalah gambaran umum tentang cara dokumentasi akan ditentukan untuk REST API.
Jadwal untuk project ini adalah sebagai berikut :
1 Agustus - 1 September
Berkenalan dengan mentor saya dan membahas lebih mendalam tingkat dokumentasi yang diperlukan di berbagai bagian codebase, serta membahas seberapa mendalam dokumentasi tingkat rendah vs dokumentasi tingkat tinggi. Saya juga akan menghabiskan waktu ini untuk memahami codebase dan mempelajari konsepnya agar dapat mendokumentasikannya dengan lebih baik.
Minggu 1 &2
Saya akan memperbarui dan memperluas panduan kontributor. Saya akan meningkatkan kualitas dokumentasi tentang cara mem-build kode sumber. Kami juga akan menambahkan bagian pembuat dokumen tentang cara kontributor baru dapat membantu dalam dokumentasi. Saya akan mempelajari berbagai dokumentasi API dan memulai dengan pengantar serta menambahkan autentikasi untuk API.
Minggu 3 - 8
Saya akan menambahkan rute dan respons API beserta beberapa contoh kode untuk setiap jenis API (mungkin ada jenis API yang serupa).
Minggu ke-9 &10
Tambahkan struktur dokumentasi API menggunakan link, yaitu indeks tertaut untuk dokumentasi API yang panjang dan bagi lebih lanjut berdasarkan dasar yang berbeda seperti bagian kode, ringkasan, parameter, endpoint root.
Minggu Terakhir
Saya akan menggunakan minggu terakhir untuk menyiapkan laporan akhir tentang pekerjaan yang dilakukan selama periode dokumentasi 12 minggu. Saya juga akan menggunakan waktu ini untuk meninjau dan menyelesaikan dokumentasi.