Bu sayfada, Google Dokümanlar Sezonu için kabul edilen bir teknik yazım projesinin ayrıntıları yer almaktadır.
Proje özeti
- Açık kaynak kuruluşu:
- OpenMRS.org
- Teknik yazar:
- batbrain7
- Proje adı:
- OpenMRS REST API dokümanları
- Proje uzunluğu:
- Standart uzunluk (3 ay)
Proje açıklaması
Teklifimi farklı bölümlere ayıracağım ve Google Haritalar API dokümanları ile Github API dokümanları gibi bir akış izleyeceğim.
Bunların dışında, realworld.io tarafından oluşturulan API dokümanları için bir readme yapısı da önermek isterim: https://github.com/gothinkster/realworld/tree/master/api
Şahsen bu dokümanları anlamanın ve kullanmanın çok kolay olduğunu düşünüyorum.
Teklifimiz temel olarak 3 bölümden oluşacaktır :
API hakkında, OpenMRS'e, API'nin nasıl kullanıldığına ve sonrasında neler olacağına dair kısa bir girişin olduğu bir bölüm.
API isteği yapmak için genel olarak gereken API anahtarını ve kimlik doğrulamayı alma. Bu, API'de bulunan kimlik doğrulama türleri ve bu kimlik için bulunması gereken anahtarlar ile değerlerin yanı sıra bu bölümdeki anahtara karşılık kabul edilen değer türlerine dair örnek bir örnek olacaktır. API'deki başlıkları, yanıt biçimlerini ve diğer sorgu parametrelerini nasıl yazacağınızı açıklığa kavuşturmak için herhangi bir dilde bir kod örneği paylaşabilirsiniz.
API tarafından getirilen yanıt türleri, JSON türleri veya API'ler tarafından döndürülen diğer sonuç türleri belirtilmelidir.
Farklı API yolları ve bunlarla birlikte gönderilmesi gereken tüm parametreler, başlıklar ve diğer öğeler. Her API için, kodu yazılırken isteğin nasıl yapıldığını açıklayan birkaç dilde kod örnekleri sağlanır. Ayrıca her API ile karşılaşılabilecek genel hata kodlarından da bahsedilmelidir.
Bu, REST API için dokümanların nasıl tanımlanacağına dair genel bir fikirdir.
Projenin zaman çizelgesi şu şekildedir :
1 Ağustos - 1 Eylül
Mentörümle tanışıp kod tabanının farklı bölümlerinde gereken dokümantasyon düzeyini daha ayrıntılı bir şekilde tartışın ve ayrıca düşük düzey ve yüksek düzey dokümantasyonda ne kadar ayrıntılı olacağınıza karar verin. Bu süreyi, kod tabanını anlamak ve daha iyi dokümante edebilmek için kavramları incelemek için de kullanacağım.
1. ve 2. hafta
Katkıda bulunanlar kılavuzunu güncelleyip genişleteceğiz. Kaynak kodunu derlemeyle ilgili dokümanları iyileştireceğiz. Ayrıca, yeni katkıda bulunanların dokümanlara nasıl yardımcı olabileceğiyle ilgili belgeleyiciler bölümü de ekleyeceğim. Farklı API dokümanlarını inceleyip girişten başlayarak API için kimlik doğrulamasını ekleyeceğim.
3 - 8. Hafta
Her API türü için API rotalarını ve yanıtlarını bazı kod örnekleriyle birlikte ekleyeceğim (benzer API türleri olabilir).
9. ve 10. Hafta
API dokümanlarını bağlantılar (ör.uzun API dokümanları için bağlantılı bir dizin) kullanarak yapılandırın ve kod bölümleri, genel bakış, parametreler, kök uç noktalar gibi farklı ölçütlere göre daha da bölün.
Son Hafta
Son haftayı, 12 haftalık dokümantasyon dönemimde yapılan çalışmalarla ilgili nihai raporumu hazırlamak için kullanacağım. Bu süre boyunca belgeleri de inceleyip son haline getireceğim.