Diese Seite enthält die Details eines Projekts für technisches Schreiben, das für die Google-Staffel von Google Docs akzeptiert wurde.
Projektzusammenfassung
- Open-Source-Organisation:
- OpenMRS.org
- Technischer Redakteur:
- batbrain7
- Projektname:
- Dokumentation zur OpenMRS REST API
- Projektdauer:
- Standarddauer (3 Monate)
Projektbeschreibung
Ich werde meinen Vorschlag in verschiedene Abschnitte aufschlüsseln und dem Ablauf folgen, z. B. der Google Maps API-Dokumentation und der GitHub API-Dokumentation.
Abgesehen davon möchte ich auch eine Readme-Struktur für die API-Dokumentation von realworld.io vorschlagen: https://github.com/gothinkster/realworld/tree/master/api.
Ich persönlich fand diese Dokumentation sehr leicht zu verstehen und zu verwenden.
Mein Vorschlag besteht im Wesentlichen aus drei Abschnitten :
Dieser Abschnitt bietet eine kurze Einführung in die API, OpenMRS und die Verwendung der API sowie die darauf folgenden Punkte.
Wie Sie den API-Schlüssel und die allgemein für die API-Anfrage erforderliche Authentifizierung erhalten. Hier sehen Sie ein Beispiel für die Authentifizierungstypen in der API, die Schlüssel und Werte, die für die API vorhanden sein müssen, sowie die Typen von Werten, die entsprechend dem Schlüssel in diesem Teil akzeptiert werden. Ein Codebeispiel in einer beliebigen Sprache würde helfen und das Schreiben der Header und Antwortformate sowie anderer Abfrageparameter in der API vereinfachen.
Erwähnenswert sind die Antworttypen, die von der API abgerufen werden, die Typen von JSON oder andere Ergebnistypen, die von den APIs zurückgegeben werden.
Die verschiedenen API-Routen und die zugehörigen Parameter, die zusammen mit den Headern und anderen Elementen gesendet werden müssen Jede API wird von Codebeispielen in einigen Sprachen unterstützt, in denen beschrieben wird, wie die Anfrage beim Schreiben des Codes dafür gestellt wird. Abgesehen von den allgemeinen Fehlercodes, die bei den einzelnen APIs auftreten können, sollte ebenfalls erwähnt werden.
Dies ist eine allgemeine Vorstellung davon, wie die Dokumentation für die REST API definiert wird.
Der Zeitplan für das Projekt sieht so aus :
1. August–1. September
Mach dich mit meinem Mentor vertraut, besprich den Umfang der Dokumentation, die an verschiedenen Teilen der Codebasis erforderlich ist, und erläutere auch, wie detailliert die Low-Level- im Vergleich zur High-Level-Dokumentation aussehen sollte. Außerdem werde ich diese Zeit damit verbringen, die Codebasis zu verstehen und die Konzepte zu lernen, damit ich sie besser dokumentieren kann.
Woche 1 und 2
Ich werde den Leitfaden für Beitragende aktualisieren und erweitern. Ich werde die Dokumentation zum Erstellen des Quellcodes verbessern. Ich werde auch einen Dokumentarbereich hinzufügen, in dem es darum geht, wie neue Beitragende bei der Dokumentation helfen können. Ich werde mir die verschiedenen API-Dokumentationen ansehen, mit der Einführung beginnen und die Authentifizierung für die API hinzufügen.
Woche 3–8
Ich füge die API-Routen und -Antworten zusammen mit einigen Codebeispielen für jeden API-Typ hinzu (es gibt möglicherweise ähnliche API-Typen).
Woche 9 und 10
Fügen Sie die API-Dokumentation mithilfe von Links hinzu, d. h. einen verknüpften Index für eine lange API-Dokumentation, und unterteilen Sie sie nach Codeabschnitten, Übersicht, Parametern und Stammendpunkten.
Letzte Woche
In der letzten Woche erstelle ich meinen Abschlussbericht über die Arbeit, die ich während der 12-wöchigen Dokumentationsphase geleistet habe. Außerdem werde ich diese Zeit damit verbringen, die Dokumentation zu prüfen und fertigzustellen.