Diese Seite enthält die Details zu einem Projekt für technisches Schreiben, das für die Google-Produktsaison 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. in der Google Maps API-Dokumentation und der GitHub API-Dokumentation.
Außerdem möchte ich eine Readme-Struktur für die API-Dokumentation von realworld.io vorschlagen: https://github.com/gothinkster/realworld/tree/master/api.
Mir persönlich fand ich diese Dokumentation sehr leicht verständlich und benutzerfreundlich.
Mein Vorschlag besteht im Wesentlichen aus drei Abschnitten :
Dieser Abschnitt bietet eine kurze Einführung in das API, OpenMRS und die Verwendung der API sowie die folgenden Punkte.
Hier erfahren Sie, wie Sie den API-Schlüssel und die Authentifizierung abrufen, die allgemein für die API-Anfrage erforderlich sind. 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 zu verdeutlichen, wie die Header und Antwortformate sowie andere Abfrageparameter in der API geschrieben werden.
Erwähnen Sie 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 was alle Parameter zusammen mit diesen, den Headern und anderen Elementen gesendet werden müssen. Jede API wird von Codebeispielen in einigen Sprachen unterstützt, die beschreiben, wie die Anfrage beim Schreiben des Codes dafür gestellt wird, abgesehen von den allgemeinen Fehlercodes, die bei jeder API auftreten können.
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
Machen Sie sich mit meinem Mentor vertraut und besprechen Sie den Umfang der Dokumentation, die in verschiedenen Teilen der Codebasis erforderlich ist, und erläutern Sie, wie detailliert die Low-Level- im Vergleich zu High-Level-Dokumentation aussehen sollte. Außerdem werde ich diese Zeit damit verbringen, die Codebasis zu verstehen und die Konzepte zu studieren, 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 Abschnitt für Dokumentationen hinzufügen, in dem beschrieben wird, 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 kann ähnliche Arten von APIs geben).
Woche 9 und 10
Fügen Sie die Strukturierung der API-Dokumentation mithilfe von Links, d. h. einem verknüpften Index für eine lange API-Dokumentation, hinzu und unterteilen Sie sie auf eine andere Basis wie Codeabschnitte, Übersicht, Parameter und Stammendpunkte.
Letzte Woche
Ich werde die letzte Woche nutzen, um meinen Abschlussbericht über die Arbeiten zu erstellen, die während meiner 12-wöchigen Dokumentationsphase geleistet wurden. Außerdem werde ich diese Zeit damit verbringen, die Dokumentation zu prüfen und fertigzustellen.