Questa pagina contiene i dettagli di un progetto di scrittura tecnica accettato per la stagione dei documenti Google.
Riepilogo del progetto
- Organizzazione open source:
- OpenMRS.org
- Technical writer:
- batbrain7
- Nome progetto:
- Documentazione sull'API REST di OpenMRS
- Durata del progetto:
- Durata standard (3 mesi)
Project description
Analizzerò la mia proposta in diverse sezioni e seguirò il flusso, come la documentazione dell'API di Google Maps e la documentazione dell'API GitHub.
Oltre a questi, vorrei anche proporre una struttura Leggimi per la documentazione dell'API realizzata da realworld.io: https://github.com/gothinkster/realworld/tree/master/api
Personalmente, ritengo che la documentazione sia molto facile da capire e utilizzare.
La mia proposta si compone principalmente di tre sezioni :
Una sezione che offre una rapida introduzione all'API, a OpenMRS e a come viene utilizzata l'API e a ciò che segue.
Come ottenere la chiave API e l'autenticazione necessaria in generale per effettuare la richiesta API. Questo sarà un esempio di esempio dei tipi di autenticazione presenti nell'API e delle chiavi e dei valori che devono essere presenti nell'API, nonché dei tipi di valori accettati corrispondenti alla chiave in quella parte. Un esempio di codice in qualsiasi linguaggio consente di capire come scrivere intestazioni e formati di risposta e altri parametri di query nell'API.
È necessario indicare i tipi di risposte recuperate dall'API, i tipi di JSON o qualsiasi altro tipo di risultato restituito dalle API.
Le diverse route API e i parametri che devono essere inviati insieme a queste, intestazioni e altri elementi. Ogni API sarà assistita da esempi di codice in alcuni linguaggi che descrivono come viene effettuata la richiesta durante la scrittura del relativo codice, a parte i codici di errore generali che si potrebbero trovare con ogni API.
Questa è un'idea generale di come verrà definita la documentazione per l'API REST.
La pianificazione del progetto è la seguente :
1° agosto - 1° settembre
Fai conoscenza con il mio mentore e discuti in modo più approfondito del livello di documentazione richiesto in diverse parti del codebase e discuti di quanto sia approfondito la documentazione di basso e di alto livello. Inoltre, dedicherò questo tempo a comprendere il codebase e studierò i concetti in modo da documentarli meglio.
Settimana 1 e 2
Aggiornerò ed estenderò la guida per i collaboratori. Migliorerò la documentazione su come creare il codice sorgente. Aggiungerò anche una sezione dedicata ai documentari su come i nuovi collaboratori possono aiutare nella documentazione. Studierò la diversa documentazione dell'API, inizierò con l'introduzione e aggiungerò l'autenticazione per l'API.
Settimana 3 - 8
Aggiungerò le route e le risposte delle API insieme ad alcuni esempi di codice per ogni tipo di API (potrebbero esserci tipi di API simili).
Settimana 9 e 10
Aggiungi la struttura della documentazione API utilizzando i link, ad esempio un indice collegato per la lunga documentazione dell'API, e dividilo ulteriormente in base a sezioni di codice, panoramica, parametri, endpoint root.
Settimana finale
Userò l'ultima settimana per preparare il mio rapporto finale sul lavoro svolto durante il periodo di documentazione di 12 settimane. Dedicherò anche questo tempo a esaminare e finalizzare la documentazione.